A RESTful API for Pokémon - pokeapi.co
Beta GraphQL support is rolling out! Check out the GraphQL paragraph for more info.
Table of Contents
Setup 
[!NOTE]
The data/v2/cries submodule (~25 MB) is required to build cry sound URLs.
The sprites submodule (10+ GB) is optional, the database build automatically downloads the lightweight sprite manifest when building data. If you wish to clone all submodules locally, you can pass --recurse-submodules.
-
Install uv for Python environment management.
-
Install the requirements using the Makefile commands:
make install
# This will install all the required packages and libraries for using PokeAPI
-
Install the pre-commit hooks using the Makefile commands (optional but recommended):
make pre-commit-install
Pre-commit hooks are optional but recommended for maintaining code quality and consistency. If you do not want it to automatically run on every commit, you can run it manually with make pre-commit before committing and pushing your changes.
-
Lint, format, and typecheck your code changes:
make lint-check # or: uv run ruff check .
make format # or: uv run ruff format .
make typecheck # or: uv run ty check
As of right now we are not strictly enforcing linting and typechecking, but we will be in the future. Please try to make sure your code passes these checks.
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.
Environment Variables
The database build supports several optional environment variables:
| Variable |
Default |
Description |
POKEAPI_SPRITES_PREFIX |
https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/ |
Base URL prefix used for sprite URLs in API responses. |
POKEAPI_CRIES_PREFIX |
https://raw.githubusercontent.com/PokeAPI/cries/main/cries/ |
Base URL prefix used for Pokémon cry sound file URLs. |
POKEAPI_SPRITES_MANIFEST_URL |
https://pokeapi.github.io/sprites/manifest.json.gz |
Custom URL for downloading the sprite manifest.json.gz. |
POKEAPI_USE_LOCAL_SPRITES |
0 |
Set to 1 to force scanning local cloned sprites submodule (data/v2/sprites/sprites/) instead of using the remote manifest. |
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.
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/2.0/hasura-cli/install-hasura-cli
# hasura cli's version has to greater than v2.50.2
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 /graphql/v1beta/examples and /graphql/v1beta2/examples directories 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
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 Discord!
We have a Discord server. It is a simple place where people can chat with each other in a respecful manner. Not all maintainers/code contributors are signed up and your question might not be answered. Consider opening an issue if you want more visibility or you want to talk to the maintainers. Be excellent to each other :smile:
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!
评论