pokeapi / api-data

Static JSON data from the API, plus a JSON Schema

A RESTful API for Pokémon - pokeapi.co

Beta GraphQL support is rolling out! Check out the GraphQL paragraph for more info.

Setup  

• Download this source code into a working directory, be sure to use the flag --recurse-submodules to clone also our submodules.

• Install the requirements using pip:

  make install
  # This will install all the required packages and libraries for using PokeAPI

• Set up the local development environment using the following command:

  make setup

• Run the server on port 8000 using the following command:

  make serve

Database setup

To build or rebuild the database by applying any CSV file update, run

make build-db

Visit localhost:8000/api/v2/ to see the running API!

Each time the build-db script is run, it will iterate over each table in the database, wipe it, and rewrite each row using the data found in data/v2/csv.

If you ever need to wipe the database use this command:

make wipe-sqlite-db

If the database schema has changed, generate any outstanding migrations and apply them

make make-migrations
make migrate

Run make help to see all tasks.

Docker and Compose  

There is also a multi-container setup, managed by Docker Compose V2. This setup allows you to deploy a production-like environment, with separate containers for each service, and is recommended if you need to simply spin up PokéAPI.

Start everything by

make docker-setup

If you don't have make on your machine you can use the following commands

docker compose up -d
docker compose exec -T app python manage.py migrate --settings=config.docker-compose
docker compose exec -T app sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker-compose'

Browse localhost/api/v2/ or localhost/api/v2/pokemon/bulbasaur/ on port 80.

To rebuild the database and apply any CSV file updates, run

make docker-build-db

If the database schema has changed, generate the migrations and apply those

make docker-make-migrations
make docker-migrate

GraphQL  

When you start PokéAPI with the above Docker Compose setup, an Hasura Engine server is started as well. It's possible to track all the PokeAPI tables and foreign keys by simply

# hasura cli needs to be installed and available in your $PATH: https://hasura.io/docs/latest/graphql/core/hasura-cli/install-hasura-cli.html
# hasura cli's version has to greater than v2.0.8
make hasura-apply

When finished browse http://localhost:8080 and you will find the admin console. The GraphQL endpoint will be hosted at http://localhost:8080/v1/graphql.

A free public GraphiQL console is browsable at the address https://beta.pokeapi.co/graphql/console/. The relative GraphQL endpoint is accessible at https://beta.pokeapi.co/graphql/v1beta

A set of examples is provided in the directory /graphql/examples of this repository.

Kubernetes  

Kustomize files are provided in the folder https://github.com/PokeAPI/pokeapi/tree/master/Resources/k8s/kustomize/base/. Create and change your secrets:

cp Resources/k8s/kustomize/base/secrets/postgres.env.sample Resources/k8s/kustomize/base/secrets/postgres.env
cp Resources/k8s/kustomize/base/secrets/graphql.env.sample Resources/k8s/kustomize/base/secrets/graphql.env
cp Resources/k8s/kustomize/base/config/pokeapi.env.sample Resources/k8s/kustomize/base/config/pokeapi.env
# Edit the newly created files

Configure kubectl to point to a cluster and then run the following commands to start a PokéAPI service.

kubectl apply -k Resources/k8s/kustomize/base/
kubectl config set-context --current --namespace pokeapi # (Optional) Set pokeapi ns as the working ns
# Wait for the cluster to spin up
kubectl exec --namespace pokeapi deployment/pokeapi -- python manage.py migrate --settings=config.docker-compose # Migrate the DB
kubectl exec --namespace pokeapi deployment/pokeapi -- sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker-compose' # Build the db
kubectl wait --namespace pokeapi --timeout=120s --for=condition=complete job/load-graphql # Wait for Graphql configuration job to finish

This k8s setup creates all k8s resources inside the Namespace pokeapi, run kubectl delete namespace pokeapi to delete them. It also creates a Service of type LoadBalancer which is exposed on port 80 and 443. Data is persisted on 12Gi of ReadWriteOnce volumes.

Wrappers

Official wrapper	Repository	Features
Node server-side	PokeAPI/pokedex-promise-v2	Auto caching
Browser client-side	PokeAPI/pokeapi-js-wrapper	Auto caching, Image caching
Java/Kotlin	PokeAPI/pokekotlin
Python 2/3	PokeAPI/pokepy	Auto caching
Python 3	PokeAPI/pokebase	Auto caching, Image caching

Wrapper	Repository	Features
.Net Standard	mtrdp642/PokeApiNet	Auto caching
Dart	prathanbomb/pokedart
Go	mtslzr/pokeapi-go	Auto caching
PHP	lmerotta/phpokeapi	Auto caching, lazy loading
PowerShell	Celerium/PokeAPI-PowerShellWrapper
Python	beastmatser/aiopokeapi	Auto caching, asynchronous
Ruby	rdavid1099/poke-api-v2
Rust	lunik1/pokerust	Auto caching
Scala	juliano/pokeapi-scala	Auto caching
Spring Boot	dlfigueira/spring-pokeapi	Auto caching
Swift	kinkofer/PokemonAPI
Typescript server-side/client-side	Gabb-c/Pokenode-ts	Auto caching

Donations

Help to keep PokéAPI running! If you're using PokéAPI as a teaching resource or for a project, consider sending us a donation to help keep the service up. We get 1+ billion requests a month!

Thank you to all our backers! Become a backer

Join Us On Slack!

Warning Currently no maintainer has enough free time to support the community on Slack. Our Slack is in an unmaintained status.

Have a question or just want to discuss new ideas and improvements? Hit us up on Slack. Consider talking with us here before creating a new issue. This way we can keep issues here a bit more organized and helpful in the long run. Be excellent to each other 😄

Sign up easily!

Once you've signed up visit PokéAPI on Slack

Contributing

This project exists thanks to all the people who contribute

All contributions are welcome: bug fixes, data contributions, and recommendations.

Please see the issues on GitHub before you submit a pull request or raise an issue, someone else might have beat you to it.

To contribute to this repository:

• Fork the project to your own GitHub profile

• Download the forked project using git clone:

  git clone --recurse-submodules [email protected]:<YOUR_USERNAME>/pokeapi.git

• Create a new branch with a descriptive name:

  git checkout -b my_new_branch

• Write some code, fix something, and add a test to prove that it works. No pull request will be accepted without tests passing, or without new tests if new features are added.

• Commit your code and push it to GitHub

• Open a new pull request and describe the changes you have made.

• We'll accept your changes after review.

Simple!

Deprecation

As of October 2018, the v1 API has been removed from PokéAPI. For more information, see pokeapi.co/docs/v1.html.

api-data's Issues

Build bot

Create a build bot to regularly release a post-transform archive like this one: https://github.com/PokeAPI/api-data/releases/tag/2018-09-22

Perhaps it's a good idea to roll that into the updater bot?

Incomplete effect information about "Azure Flute"

api-data/data/api/v2/item/432/index.json

Line 11 in af35d8b

"effect": "Supposedly related to t",

Remove '/api' from URLs

If we plan on hosting the API at api.pokeapi.co (as per pokeapi#355), shouldn't the API URL be like api.pokeapi.co/v2/ability/1 rather than api.pokeapi.co/api/v2/ability/1? Having the api in there twice seems redundant.

Incorrect sprite URLs. Base URL is duplicated.

This commit has incorrectly generated sprite URLs. The base URL is duplicated.
https://github.com/PokeAPI/api-data/blame/2d0dcd33d1907f4dfcdabab142ab97bafc6569fc/data/api/v2/pokemon/1/index.json#L11963

Expected:
front_default: "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/35.png"

Actual:
front_default: "https://raw.githubusercontent.com/PokeAPI/sprites/master/https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/35.png"

Add a deploy to netlify button

https://www.netlify.com/docs/deploy-button/

This will make it easy for users to launch their own instance of the API

Default picture

I mentioned this in PokeAPI/pokedex-promise-v2#61 before.

The idea was to set a default picture in the case that a API element need one but has none.

This is already did in some of the items in the API data, which use a question mark picture in pixel art.

Incomplete information about stantler and wyrdeer....evolution is not being considered

Make the repo independent of base url

Stop hardcoding it and depend on an env variable (set in Netlify). Users launching their own instance can set their own too. If the base url isn't provided, use relative paths (same as empty base url).

Error 503 Backend unavailable, connection timeout

I'm getting this error requesting to this url: https://raw.githubusercontent.com/PokeAPI/api-data/master/data/api/v2/pokemon/504/index.json

Error 503 Backend unavailable, connection timeout
Backend unavailable, connection timeout

Guru Mediation:
Details: cache-hkg17929-HKG 1591171890 2855085221

Varnish cache server

Use `make` when spinning up PokeAPI

api-data/updater/cmd.bash

Lines 26 to 28 in 47773d9

	docker compose -f docker-compose.yml -f docker-compose-dev.yml up -d
	docker compose exec -T app python manage.py migrate --settings=config.docker-compose
	docker compose exec -T app sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker-compose'

Why are we using the docker compose dev file?

Better to use make docker-setup?

API call pulls wrong id's for Gen 9 Pokemon

The GET API call for "https://pokeapi.co/api/v2/" for a lot of Pokemon from Generation 9 are pulling incorrect id's.
See attached files. pokemon_correct.csv displays the correct id and name information, and pokemon_incorrect.csv was created from the following code:

import requests
import csv

# Set up the base URL for the PokeAPI
base_url = "https://pokeapi.co/api/v2/"

# Define the range of Pokemon IDs to list
start_id = 906
end_id = 1010

# Create a list to hold the Pokemon data
pokemon_data_list = []

# Loop through the range of IDs and make a request to the PokeAPI for each Pokemon
for pokemon_id in range(start_id, end_id+1):
    # Construct the URL for the Pokemon with this ID
    url = base_url + f"pokemon/{pokemon_id}/"
    
    # Make a request to the PokeAPI for information about the Pokemon
    response = requests.get(url)
    
    # If the response was successful (i.e. the status code is 200), add the Pokemon's data to the list
    if response.status_code == 200:
        pokemon_data = response.json()
        pokemon_name = pokemon_data["name"]
        pokemon_data_list.append([pokemon_id, pokemon_name])
        
# Write the Pokemon data to a .csv file
with open("pokemon.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["ID", "Name"])
    writer.writerows(pokemon_data_list)
    
print("Saved Pokemon data to pokemon_incorrect.csv")

Incorrect text for leftovers in the Spanish version group x-y

https://github.com/PokeAPI/api-data/blob/master/data/api/v2/item/211/index.json#L177

It should be something like this: "Este objeto restaura gradualmente durante el\ncombate los PS del Pok\u00e9mon que lo lleva."

Broken image URLs?

It seems like the latest automated commit (318bdcb) broke many image URLs. Is there a reason for this?

Missing Deoxys-attack species info

I see that Deoxys attack form is missing data. All other variants (defense, normal, and speed) are correctly inserted.

Can you confirm that species info is missing?

Incorrect key `main_generation` should be `main_region`

When looking at the schema for region, you will find that one of the keys listed is main_generation. When retrieving data from this endpoint, you will recieve a main_region datafield, the docs align with this data. I think this is just a simple mistake, which can just be fixed by replacing it with the correct terms. The mistake occurs at line 13 and 60.

Missing base experience data for gen 9

Hello,

the field base_experience is null for all Pokemon with an id higher than 898.

Examples:
https://github.com/PokeAPI/api-data/blob/master/data/api/v2/pokemon/899/index.json
...
https://github.com/PokeAPI/api-data/blob/master/data/api/v2/pokemon/1010/index.json

Thank you for maintaing this repo and have a great day!

Incorrect sprite URLs

Something's gone wrong lately with the sprite URLs, they're a malformed concatenation of a partial URL followed by the full URL, e.g.:

https://raw.githubusercontent.com/PokeAPI/sprites/master/https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/back/1.png

Note the https:// in the middle of the URL

Seems like it affects every single sprite URL
See https://github.com/PokeAPI/api-data/blob/master/data/api/v2/pokemon-form/1/index.json as an example

Legends arceus pokeballs missing

Hi, I'm currently writing a program that pulls a list of all pokeballs and associates sprites from PokeAPI to update itself. Unfortunately, it appears that legends arceus pokeballs are not present in the current version of the database (in neither the base V2 API, or the GraphQL variant)

I'd like it if these could be added for to have all the pokeballs available to me. Thanks in advance!

Missing Varieties for Burmy.

Burmy's default form is Plant Cloak, which is there, however it appears to be missing the Trash Cloak and Sandy Cloak.

https://raw.githubusercontent.com/PokeAPI/api-data/master/data/api/v2/pokemon-species/412/index.json

The evolution, Wormadam, has all the cloaks.

Allow checkout of branch/tag/commit

api-data/updater/cmd.bash

Line 18 in eda1fc1

git clone --recurse-submodules "$REPO_POKEAPI" pokeapi

Right now the updater always uses the master branch of Pokeapi. We should allow to checkout different elements, such as a specific commit.

Occasionally a resource list request returns a 400 response

A retry always works.

The error is from this code:

api-data/functions/resource-list.js

Lines 78 to 83 in 2e21d03

	let path = "/api/v2/" + event.queryStringParameters.endpoint + "/";
	if (!path) {
	callback(null, {statusCode: 400, body: "path must not be empty"});
	return;
	}

Looks like sometimes the endpoint name isn't being passed to the function. May be another Netlify bug.

API validity broken

Hello !

I'm currently working on my library wrapping PokeAPI. By default, I set everything as nullable.
However, after checking this repo and looking in data/schema, I wanted to remove those nullable to be valid to the json schemas.

Unfortunately, if I'm not mistaken, the schemas seem outdated. For example:
ContestEffect json schema says there is 2 keys in flavor_text_entries inner data type, flavor_text and language. But in PokeAPI official docs flavor_text_entries inner type is FlavorText and there is a new key that the json schema doesn't mention: version.

After a quick call to the API, it seems the official doc is the one to follow, but the official doc doesn't state which fields are nullable and which fields aren't.

So which documentation should I trust ? If possible, can you regenerate the schemas (and maybe regenerate them regurlary like the data) ?

Thanks for you attention.
I'm open to discuss the topic :)

pokemon_forms missing Home sprites

I noticed that you can access the Home sprites on the pokemon model now, but for some forms, i.e Unown, their forms still only have the old sprite data.

Sub resourcing

According to PokeAPI/pokeapi#180 a useful upgrade to a possible Pokeapi v2.1 could be subresourcing.

At that moment in time it seemed very difficult to implement it, and in fact, it was implemented only for the encounters key in the pokemon endpoint.

Right now I see the implementation of sub resourcing relatively easy. One could think of an invoking the API with a certain querystring to only query what he wants.

https://pokeapi-prod.netlify.com/api/v2/pokemon/21/?keys=height,id,name

I'm not sure if the keys query parameter is a good name but I think that this idea could save us a large portion of bandwidth and an even more fast response time.

To implement this feature one could create a similar function to this one

api-data/functions/resource-list.js

Lines 72 to 102 in c1a800b

	exports.handler = (event, context, callback) => {
	if (event.httpMethod !== "GET") {
	callback(null, {statusCode: 405, body: event.httpMethod + " not allowed"});
	return;
	}
	let path = "/api/v2/" + event.queryStringParameters.endpoint + "/";
	if (!path) {
	callback(null, {statusCode: 400, body: "path must not be empty"});
	return;
	}
	let url = targetUrlForPath(path);
	getJson(url, (error, response) => {
	if (error) {
	callback(null, {statusCode: 400, body: "path must be a valid resource list"});
	return;
	}
	let params = extractParams(event.queryStringParameters);
	let resultSlice = response.results.slice(params.offset, params.offset + params.limit);
	let finalResponse = Object.assign(response, {
	next: getPageUrl(path, getNextPage(params, response.count)),
	previous: getPageUrl(path, getPreviousPage(params)),
	results: resultSlice,
	});
	callback(null, {statusCode: 200, body: JSON.stringify(finalResponse, null, 4)})
	});

Run build job only on `master`

Right now there is an error in our CircleCI's config.yml file and it's executed every time a branch is pushed, not only when the master is pushed. Basically the filter section is ignored

jobs: build: extraneous key [filters] is not permitted

The behavior can be seen here: https://app.circleci.com/pipelines/github/PokeAPI/api-data?branch=testbranch

This is extremely dangerous since broken branches trigger broken updates to our productive landscape.

We should use workflows https://support.circleci.com/hc/en-us/articles/115015953868-Filter-branches-for-jobs-and-workflows

Issues running updater-bot

This is a new issue to track the current problem updating api-data, that has been discussed elsewhere.

It's affected by the same problem that brought down the live API (before we replaced it with pre-generated api-data):

from @sargunv in PokeAPI/pokeapi#369:

My spitball guess is it's either a broken dependency or some sort of bug caused by system time rolling past a certain value. Anyone got any idea?