Skip to content

PokeAPI/pokeapi-js-wrapper

Repository files navigation

pokeapi-js-wrapper

npm Tests Mocha browser tests codecov

Maintainer: Naramsim

A PokeAPI wrapper intended for browsers only. Comes fully asynchronous (with localForage) and built-in cache. Offers also Image Caching through the inclusion of a Service Worker. For a Node (server-side) wrapper see: pokedex-promise-v2

Install

npm install pokeapi-js-wrapper --save
<script src="https://unpkg.com/pokeapi-js-wrapper/dist/index.js"></script>

Usage

const Pokedex = require("pokeapi-js-wrapper")
const P = new Pokedex.Pokedex()
<script>
  const P = new Pokedex.Pokedex()
</script>

Example requests

// with await, be sure to be in an async function (and in a try/catch)
(async () => {
  const golduck = await P.getPokemonByName("golduck")
  console.log(golduck)
})()

// or with Promises
P.getPokemonByName("eevee")
  .then(function(response) {
    console.log(response)
  })

P.resource([
  "/api/v2/pokemon/36",
  "api/v2/berry/8",
  "https://pokeapi.co/api/v2/ability/9/",
]).then( response => {
  console.log(response)
})

Configuration

Pass an Object to Pokedex() in order to configure it. Available options: protocol, hostName, versionPath, cache, timeout(ms), and cacheImages. Any option is optional 😄. All the default values can be found here

const Pokedex = require("pokeapi-js-wrapper")
const customOptions = {
  protocol: "https",
  hostName: "localhost:443",
  versionPath: "/api/v2/",
  cache: true,
  timeout: 5 * 1000, // 5s
  cacheImages: true
}
const P = new Pokedex.Pokedex(customOptions)

Caching images

Pokeapi.co serves its Pokemon images through Github. For example, the front default DreamWorld image of Pikachu is found at this URL: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/dream-world/25.svg.

pokeapi-js-wrapper enables browsers to cache all these images by:

  1. enabling the config parameter cacheImages
  2. serving our service worker from the root of your project

In this way when pokeapi-js-wrapper's Pokedex is created it will install and start the Service Worker you are serving at the root of your server. The Service Worker will intercept all the calls your HTML/CSS/JS are making to get PokeAPI's images and will cache them.

It's fundamental that you download the Service Worker we provide(Right Click + Save As) and you serve it from the root of your project/server. Service Workers in fact cannot be installed from a domain different than yours.

A basic example is hosted here.

Tests

pokeapi-js-wrapper can be tested using two strategies. One is with Node, since this package works with Node (although not recommended), and the other with a browser.

npm test

Or open /test/test.html in your browser. A live version can be found at gh-pages

Endpoints

All the endpoints and the functions to access PokeAPI's endpoints are listed in the long table below. Each function .ByName(name) accepts names and ids. The only 5 functions .ById(id) only accept ids. You can also pass an array to each function, it will retrieve the data for each element asynchronously.

P.getPokemonByName("eevee").then(function(response) {
  console.log(response)
})

P.getPokemonSpeciesByName(25).then(function(response) {
  console.log(response)
})

P.getBerryByName(["cheri", "chesto", 5]).then(function(response) {
  // `response` will be an Array containing 3 Objects
  // response.forEach((item) => {console.log(item.size)}) // 80,50,20
  console.log(response)
})

P.getMachineById(3).then(function(response) {
  console.log(response)
})
Function Mapped PokeAPI endpoint Documentation
getBerryByName(name) /berry/:name Documentation
getBerryFirmnessByName(name) /berry-firmness/:name Documentation
getBerryFlavorByName(name) /berry-flavor/:name Documentation
getContestTypeByName(name) /contest-type/:name Documentation
getContestEffectById(id) /contest-effect/:id Documentation
getSuperContestEffectById(id) /super-contest-effect/:id Documentation
getEncounterMethodByName(name) /encounter-method/:name Documentation
getEncounterConditionByName(name) /encounter-condition/:name Documentation
getEncounterConditionValueByName(name) /encounter-condition-value/:nam/ Documentation
getEvolutionChainById(id) /evolution-chain/:id Documentation
getEvolutionTriggerByName(name) /evolution-trigger/:name Documentation
getGenerationByName(name) /generation/:name Documentation
getPokedexByName(name) /pokedex/:name Documentation
getVersionByName(name) /version/:name Documentation
getVersionGroupByName(name) /version-group/:name Documentation
getItemByName(name) /item/:name Documentation
getItemAttributeByName(name) /item-attribute/:name Documentation
getItemCategoryByName(name) /item-category/:name Documentation
getItemFlingEffectByName(name) /item-fling-effect/:name Documentation
getItemPocketByName(name) /item-pocket/:name Documentation
getMachineById(id) /machine/:id Documentation
getMoveByName(name) /move/:name Documentation
getMoveAilmentByName(name) /move-ailment/:name Documentation
getMoveBattleStyleByName(name) /move-battle-style/:name Documentation
getMoveCategoryByName(name) /move-category/:name Documentation
getMoveDamageClassByName(name) /move-damage-class/:name Documentation
getMoveLearnMethodByName(name) /move-learn-method/:name Documentation
getMoveTargetByName(name) /move-target/:name Documentation
getLocationByName(name) /location/:name Documentation
getLocationAreaByName(name) /location-area/:name Documentation
getPalParkAreaByName(name) /pal-park-area/:name Documentation
getRegionByName(name) /region/:name Documentation
getAbilityByName(name) /ability/:name Documentation
getCharacteristicById(id) /characteristic/:id Documentation
getEggGroupByName(name) /egg-group/:name Documentation
getGenderByName(name) /gender/:name Documentation
getGrowthRateByName(name) /growth-rate/:name Documentation
getNatureByName(name) /nature/:name Documentation
getPokeathlonStatByName(name) /pokeathlon-stat/:name Documentation
getPokemonByName(name) /pokemon/:name Documentation
getPokemonEncounterAreasByName(name) /pokemon/:name/encounters Documentation
getPokemonColorByName(name) /pokemon-color/:name Documentation
getPokemonFormByName(name) /pokemon-form/:name Documentation
getPokemonHabitatByName(name) /pokemon-habitat/:name Documentation
getPokemonShapeByName(name) /pokemon-shape/:name Documentation
getPokemonSpeciesByName(name) /pokemon-species/:name Documentation
getStatByName(name) /stat/:name Documentation
getTypeByName(name) /type/:name Documentation
getLanguageByName(name) /language/:name Documentation

Root Endpoints list

For each PokeAPI's root endpoint we provide a method to get all the items served by that endpoint. By default the method will return every item in the endpoint. If needed an offset and a limit can be configured.

  • offset is where to start. The first item that you will get. Default 0
  • limit is how many items you want to list. Default 100000

TIP: Do not pass any config Object to your call, since you will get every item and everything will be cached

The following snippet will get the list of Pokémon between ID 34 and ID 44

const interval = {
  offset: 34,
  limit: 10,
}
P.getPokemonsList(interval).then(function(response) {
  console.log(response)
})
Function Mapped PokeAPI endpoint
getEndpointsList() /
getBerriesList() /berry
getBerriesFirmnesssList() /berry-firmness
getBerriesFlavorsList() /berry-flavor
getContestTypesList() /contest-type
getContestEffectsList() /contest-effect
getSuperContestEffectsList() /super-contest-effect
getEncounterMethodsList() /encounter-method
getEncounterConditionsList() /encounter-condition
getEncounterConditionValuesList() /encounter-condition-value
getEvolutionChainsList() /evolution-chain
getEvolutionTriggersList() /evolution-trigger
getGenerationsList() /generation
getPokedexsList() /pokedex
getVersionsList() /version
getVersionGroupsList() /version-group
getItemsList() /item
getItemAttributesList() /item-attribute
getItemCategoriesList() /item-category
getItemFlingEffectsList() /item-fling-effect
getItemPocketsList() /item-pocket
getMachinesList() /machine
getMovesList() /move
getMoveAilmentsList() /move-ailment
getMoveBattleStylesList() /move-battle-style
getMoveCategoriesList() /move-category
getMoveDamageClassesList() /move-damage-class
getMoveLearnMethodsList() /move-learn-method
getMoveTargetsList() /move-target
getLocationsList() /location
getLocationAreasList() /location-area
getPalParkAreasList() /pal-park-area
getRegionsList() /region
getAbilitiesList() /ability
getCharacteristicsList() /characteristic
getEggGroupsList() /egg-group
getGendersList() /gender
getGrowthRatesList() /growth-rate
getNaturesList() /nature
getPokeathlonStatsList() /pokeathlon-stat
getPokemonsList() /pokemon
getPokemonColorsList() /pokemon-color
getPokemonFormsList() /pokemon-form
getPokemonHabitatsList() /pokemon-habitat
getPokemonShapesList() /pokemon-shape
getPokemonSpeciesList() /pokemon-species
getStatsList() /stat
getTypesList() /type
getLanguagesList() /language

Custom URLs and paths

Use .resource() to query any URL or path. Also this function accepts both single values and Arrays.

P.resource([
  "/api/v2/pokemon/36",
  "api/v2/berry/8",
  "https://pokeapi.co/api/v2/ability/9/",
]).then(function(response) {
  console.log(response)
})

P.resource("api/v2/berry/5").then(function(response) {
  console.log(response)
})

Internet Explorer 8

In order to target this browser you must load a Promise polyfill before pokeapi-js-wrapper. You can choose one of your choice, we recommend jakearchibald/es6-promise or stefanpenner/es6-promise