Skip to content

Add new fields to evolutions (version_group_id, is_default, and evolved_form_id)#1558

Merged
Naramsim merged 6 commits into
PokeAPI:masterfrom
jemarq04:feat/update-evolutions
Jun 22, 2026
Merged

Add new fields to evolutions (version_group_id, is_default, and evolved_form_id)#1558
Naramsim merged 6 commits into
PokeAPI:masterfrom
jemarq04:feat/update-evolutions

Conversation

@jemarq04

@jemarq04 jemarq04 commented Jun 17, 2026

Copy link
Copy Markdown
Member

Change description

I've been brainstorming since my last PR with evolution schema changes on how to make things a bit clearer to the user. For example, retrieving the evolutions for Probopass gives an enormous list, but only one of them is the most relevant for newer games. Plus, getting evolutions for Sandshrew gives two different methods both to "Sandslash", since we mark the species as the endpoints.

This PR aims to solve some of the issues with clarity. I've added version_group_id and is_default to make it clearer which evolutions are considered the "main" one going forward to new generations (i.e. it is safe to assume that Squirtle evolves at level 16). The version group ID would describe the version group that introduced this evolution. For example, Cyndaquil evolves to Quilava at 17 in Hisui (version_group is legends-arceus and is_default is 0, since our assumption would be that in any other game it would evolve at level 14 as usual). The evolution from Quilava to Typhlosion and the one from Quilava to Hisuian Typhlosion while in Hisui are both default in this case. The Johto evolution is obvious, but I felt that the Hisuian one should also be default because any Quilava in Hisui will of course evolve to Hisuian Typhlosion and if we were to revisit this region, we should expect this behavior. A rule-of-thumb I think would be if you viewed the summary page for this pokemon on serebii (i.e. https://www.serebii.net/pokemon/quilava) if the evolution should be shown then it is a default evolution.

To additionally help with the clarity of regional evolutions, I've added the evolved_form_id to complement the region_id and base_form_id fields. Now an evolution like Meowth would have three default evolution chains:

  1. meowth to persian by level-up,
  2. meowth to persian with base_form of meowth-alola and evolved_form of persian-alola, and
  3. meowth to perrserker with base_form of meowth-galar.

Lastly, I added a couple evolutions I missed for Leafeon and Glaceon in Sun/Moon.

I know I tend to be a bit verbose in these descriptions, but I wanted to make the usage and motivation as clear as I can!

Closes #639, closes #666, closes #724, closes #729, closes #931, closes #1068, closes #1266. (There were a lot of requests to clarify regional evolutions and some for linking versions lol.)

Contributor check list

  • I have written a description of the contribution and explained its motivation.
  • I have written tests for my code changes (if applicable).
  • I have read and understood the AI Assisted Contribution guidelines.
  • I will own this change in production, and I am prepared to fix any bugs caused by my code change.

@Naramsim

Copy link
Copy Markdown
Member

Whoa, thanks for the hard job. I'll try to review some CSV later. I trust you on the implementation, so many issues will be closed with this merged in).

@Naramsim

Copy link
Copy Markdown
Member

Whao, that's crazy! I checked Muk and Persian. Great and clean solution, sorry for not merging it earlier :)

@Naramsim

Copy link
Copy Markdown
Member

And could align the docs? Amongh the new three fields version_group_id and is_default are the one that we should write a good description for. For the is_default maybe it will be a bit counter intuitive to have many trues, maybe writing that is_default is tyed to the version_group?

@Naramsim Naramsim merged commit 050ff5b into PokeAPI:master Jun 22, 2026
9 checks passed
@pokeapi-machine-user

Copy link
Copy Markdown

A PokeAPI/api-data refresh has started. In ~45 minutes the staging branch of PokeAPI/api-data will be pushed with the new generated data.

The staging branch will be deployed in our staging environment and the entire API will be ready to review.

A Pull Request (master<-staging) will be also created at PokeAPI/api-data and assigned to the PokeAPI Core team to be reviewed. If approved and merged new data will soon be available worldwide at pokeapi.co.

@pokeapi-machine-user

Copy link
Copy Markdown

The updater script has finished its job and has now opened a Pull Request towards PokeAPI/api-data with the updated data.

The Pull Request can be seen deployed in our staging environment when CircleCI deploy will be finished (check the start time of the last build).

@jemarq04 jemarq04 deleted the feat/update-evolutions branch June 22, 2026 16:04
@jemarq04

Copy link
Copy Markdown
Member Author

And could align the docs? Amongh the new three fields version_group_id and is_default are the one that we should write a good description for. For the is_default maybe it will be a bit counter intuitive to have many trues, maybe writing that is_default is tyed to the version_group?

I'm glad you're happy with the updates! This has been something in the back of my mind for some time on how to improve.

As far as the docs, I have a branch waiting to upload - I'll check it over and make the PR for it soon.

My intention with is_default is that each unique Pokemon variety that is evolved to (e.g. persian and persian-alola) has exactly one default evolution depending on the latest main generation evolution method. That's why there are so many default evolutions, I imagine that most evolutions would be default. Some newer methods (like the changing evolutions for kubfu in Scarlet/Violet) would be default and change the older methods to false. Do you still like this reasoning? If so I'll make the changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment