pokedex-promise V2 Guide

pokedex-promise-v2 is a popular, lightweight Node.js client wrapper for PokéAPI. It features built-in in-memory caching, automatic rate limiting fallback configurations, and support for Promises, Async/Await, and Callbacks.

This guide will walk you through installing the package, configuring the client, and fetching Pokémon data.

---

Getting Started

Follow these steps to integrate pokedex-promise-v2 into your Node.js application:

1. Install the package Choose your preferred package manager to add pokedex-promise-v2 to your project:

   npm

   Terminal

   npm install pokedex-promise-v2

   yarn

   Terminal

   yarn add pokedex-promise-v2

   pnpm

   Terminal

   pnpm i pokedex-promise-v2

2. Configure your project for ESM Since version 4.0.0, pokedex-promise-v2 is a pure ES Modules (ESM) package Required.

   Important ESM Requirement

   You must configure your project to support ES modules. Ensure your package.json contains:

   package.json

   {
     "name": "my-pokemon-app",
     "type": "module"
   }

   Otherwise, trying to use import in Node.js will throw a syntax error.

3. Initialize the client Import the package and initialize a new Pokedex instance.

   app.js

   import Pokedex from 'pokedex-promise-v2';
   const P = new Pokedex();

4. Run your first query Retrieve information for a Pokémon by name or ID.

   app.js

   import Pokedex from 'pokedex-promise-v2';
   const P = new Pokedex();
   const pikachu = await P.getPokemonByName("pikachu");
   console.log(`Pokedex ID: ${pikachu.id}`); // 25

   To run this file, open your terminal and press node app.js followed by Enter.

---

Querying Patterns

pokedex-promise-v2 is highly flexible. You can query endpoints using Async/Await, Promises, or traditional Callbacks. You can also fetch single records or retrieve arrays of records in a single call.

1. Main Fetching Methods

• getPokemonByName(nameOrId) Async/AwaitPromiseCallback Fetch Pokemon data by string name or integer ID.
• getPokemonSpeciesByName(nameOrId) Async/AwaitPromiseCallback Fetch species data (including language translations, evolution chains, and descriptions).

2. Implementation Patterns

Async / Await

async-await.js

import Pokedex from 'pokedex-promise-v2';
const P = new Pokedex();

try {
  const species = await P.getPokemonSpeciesByName("golduck");
  const frenchName = species.names.find(n => n.language.name === 'fr').name;
  console.log(`French name of Golduck: ${frenchName}`);
} catch (error) {
  console.error("Failed to fetch Pokémon species data:", error);
}

Promises

promises.js

import Pokedex from 'pokedex-promise-v2';
const P = new Pokedex();

// Passing an array fetches multiple records simultaneously
P.getPokemonByName(['eevee', 'ditto'])
  .then((response) => {
    console.log(response); // Array containing Eevee and Ditto data
  })
  .catch((error) => {
    console.error('Error fetching Pokémon:', error);
  });

Callbacks

callbacks.js

import Pokedex from 'pokedex-promise-v2';
const P = new Pokedex();

// You can pass an integer ID instead of a string name
P.getPokemonByName(34, (response, error) => {
  if (!error) {
    console.log(`Pokémon Name: ${response.name}`); // nidoking
  } else {
    console.error(error);
  }
});

View Pikachu Query JSON Response Payload Structure

pikachu-response.json

{
  "id": 25,
  "name": "pikachu",
  "base_experience": 112,
  "height": 4,
  "is_default": true,
  "order": 35,
  "weight": 60,
  "abilities": [
    {
      "is_hidden": false,
      "slot": 1,
      "ability": {
        "name": "static",
        "url": "https://pokeapi.co/api/v2/ability/9/"
      }
    }
  ],
  "forms": [
    {
      "name": "pikachu",
      "url": "https://pokeapi.co/api/v2/pokemon-form/25/"
    }
  ]
}

---

Advanced Configurations

By default, the client is initialized to target the public API endpoint (https://pokeapi.co/api/v2/), timeout after 20 seconds, and cache responses in memory for 11 days.

You can customize this behavior by passing a configuration object to the constructor:

config.js

import Pokedex from 'pokedex-promise-v2';

const customOptions = {
  protocol: 'https',
  hostName: 'pokeapi.co',
  versionPath: '/api/v2/',
  cacheLimit: 5 * 60 * 1000, // Cache for 5 minutes (in milliseconds)
  timeout: 5000              // Timeout after 5 seconds (in milliseconds)
};

const P = new Pokedex(customOptions);

Custom API Endpoints

If you run a local PokéAPI instance or cache-proxy on localhost, you can set hostName to 'localhost:8000' (or your local port) to redirect all client calls there!

---

Next Steps

pokedex-promise-v2 GitHubCheck the official repository for a full list of available endpoint methods.

Go to PokéAPI HomepageReturn to the main PokéAPI docs page.