Pokeapi: Unclarity in API results / documentation regarding forms/varieties of a Pokémon species

[Finrod-Amandil]

Hi dear team of the PokéAPI!
First of all, of course, thanks a thousand times for this invaluable resource!

I am currently studying the entity model the PokéApi uses as I plan on building a relational database which in parts shall be filled with data of your API. However, I have come to a question which I just don't manage to fully answer with the otherwise excellent documentation: What is the difference in your API between a "variety" on a "Pokémon species" and a "form" on a "Pokémon"?

I have previously studied the list of Pokémon with multiple forms as provided by Bulbapedia (https://bulbapedia.bulbagarden.net/wiki/List_of_Pok%C3%A9mon_with_form_differences) and they treat all forms equally, regardless of the specifications of each form. However in your API there seem to be two kinds of entities describing forms, on one hand "pokemon" and on the other "pokemon-form"

The species Vivillon for example (endpoint pokemon-species/666/) has one "variety" named "vivillon", and that variety (being an instance of "pokemon", pokemon/666/) then has 20 "pokemon-form"s.

The species Wormadam (endpoint pokemon-species/413/) however has three "varieties", each with only one "pokemon-form".

The various forms of Wormadam and Vivillon are both just treated as "forms" by Bulbapedia, and similarily I would have modelled it in my database.

The description of the "pokemon" entity in the documentation is confusing to me:

Pokémon are the creatures that inhabit the world of the Pokémon games. They can be caught using Pokéballs and trained by battling with other Pokémon. See Bulbapedia for greater detail.

It reads as if a Pokémon is one specific instance of a species, i.e. "that perfect-IV shiny rattata I caught yesterday which I nick-named 'John Cena'", but the use of it in the API much rather suggests that a "pokemon" is somewhat equal to a specific form a species can have, not a specific Pokémon.

So my question: Is there something I am missing, because I fail to see the difference between a "form" and "variety".

Thanks already for a quick answer, and maybe some clarification in the docs!

~ Finrod

[SirSkaro]

The difference between varieties and forms is minute, and is not an "official" concept to Pokemon. However, distinguishing between the two is very helpful. The API does have (brief) documentation concerning both.

From the API concerning _varieties_:
A Pokémon Species forms the basis for at least one Pokémon. Attributes of a Pokémon species are shared across all varieties of Pokémon within the species. A good example is Wormadam; Wormadam is the species which can be found in three different varieties, Wormadam-Trash, Wormadam-Sandy and Wormadam-Plant.

From the API concerning _forms_:
Some Pokémon have the ability to take on different forms. At times, these differences are purely cosmetic and have no bearing on the difference in the Pokémon's stats from another; however, several Pokémon differ in stats (other than HP), type, and Ability depending on their form.

Basically, a _variety_ of a Pokemon is a "transformation" of a Pokemon, but is still considered the same species and has the same Pokedex number though typing, abilities, and stats can differ. Another example: Kyurem, Kyurem Black, and Kyurem White are all considered to have the same species, but look different and have different stats and abilities.
A _form_ is a cosmetic change but there is no significant transformation of the Pokemon. This is why Vivillon has so many forms but one variety.

Though, if what I said is true, then I think the data for Minior is incorrect. According to https://pokeapi.co/api/v2/pokemon-species/774/. Minior has a meteor transformation and a "shields down" transformation, as well as 7 color variants. But according to this resource, permutation of color and transformation is a "variety" (for a total of 14 varieties). I think that there should be two varieties of Minior (meteor and "shields down") and 7 forms (one for each color). Stats change between transformation, but not colors.

[Finrod-Amandil]

Thanks a lot for the answer! So, if I understand you correctly, the idea is the following:

• Varieties differ in aspects other than appearance, i.e. stats, abilities, typing
• Forms differ only in appearance. Or at least you say "there is no significant transformation of the Pokémon", which is a little vague to fully grasp the idea. Also if that is what you're saying it contradicts the documentation:

however, several Pokémon differ in stats (other than HP), type, and Ability depending on their form.

Sorry to dissect your reply like this, but from experience a crooked entity model can be an enormous pain for a web application, thus I want to be extra careful around here.

So, I am now going through the entire list of "Pokémon with form differences" by bulbapedia and check out how they are represented in this API, maybe that way I can see the idea you describe.

• Pikachu: Cosplay Pikachus and Pikachus with caps. Mostly appearance only, but can not evolve and have access to exclusive moves --> VARIETIES
• Pichu: Spiky-eared: Difference in PokéAthlon stats and cannot evolve, otherwise purely visual difference --> FORMS
• Unown: Purely visual --> FORMS
• Castform: Different typings --> VARIETIES
• Deoxys: Different stats --> VARIETIES
• Burmy: Purely visual --> FORMS
• Wormadame: Different typings --> VARIETIES
• Cherrim: Different stats, but caused by ability --> FORMS
• Shellos/Gastrodon: Purely visual --> FORMS
• Rotom: Different typings, stats and learnsets --> VARIETIES
• Giratina: Different stats and abilities --> VARIETIES
• Shaymin: Different typings and abilities --> VARIETIES
• Arceus: Different typings --> FORMS :collision:!
• Basculin: Different abilities --> VARIETIES
• Darmanitan: Different typings and stats --> VARIETIES
• Deerling / Sawsbuck: Purely visual --> FORMS
• Tornadus / Thundurus / Landorus: Different stats and abilities --> VARIETIES
• Kyurem: Different stats and abilities --> VARIETIES
• Keldeo: Purely visual, although linked to moveset --> VARIETIES :collision:?
• Meloetta: Different stats and typings --> VARIETIES
• Genesect: Different types of signature move --> FORMS :collision:?
• Greninja: Different stats and abilities --> VARIETIES
• Vivillon: Purely visual --> FORMS
• Flabébé / Floette / Florges: Purely visual with the exception of Eternal Flower Floette. --> FORMS for regular colors, VARIETIES for Eternal Flower Floette with unique move.
• Furfrou: Purely visual --> FORMS
• Aegislash: Different stats --> VARIETIES
• Pumpkaboo / Gourgeist: Different stats --> VARIETIES
• Xerneas: Purely visual --> FORMS
• Zygarde: Different stats and abilities --> VARIETIES. Has four varieties - looks like Zygarde 50% exists twice... :collision:?
• Hoopa: Different typings and stats --> VARIETIES
• Oricorio: Different typings --> VARIETIES
• Lycanrock: Different stats, abilities and learnset --> VARIETIES. - Dusk form is missing (USUM) :collision:
• Wishiwashi: Different stats --> VARIETIES
• Silvally: Different typings --> FORMS :collision:!
• Minior: Two "layers" of forms: Meteor vs. Core (different stats) and colors (purely visual) --> All mapped as VARIETIES :collision: (as mentioned already)
• Mimikyu: Form grants immunity from attacks --> VARIETIES
• Necrozma: USUM forms currently not in the API :collision:

Other kinds of forms I found in the API:
Alola Forms: VARIETIES
Alola-Totem-Pokémon: VARIETIES
Mega evolutions: VARIETIES

---

Thanks again for the explanations, it seems indeed like FORM = visual difference only, with very few exceptions, which in that light seem to rather be mistakes than choices on purpose (see the :collision: markers above). In that case I would however strongly suggest to adjust the description of the Pokémon forms and Pokémon entities in the docs:

Pokémon:

Pokémon are the creatures that inhabit the world of the Pokémon games. They can be caught using Pokéballs and trained by battling with other Pokémon. See Bulbapedia for greater detail.

--> I'd rather except something along the lines of "Pokémon are the creatures that inhabit the world of the Pokémon games. They can be caught using Pokéballs and trained by battling with other Pokémon. Each Pokémon belongs to a specific species but may take on a variant which makes it differ from other Pokémon of the same species, such as base stats, available abilities and typings."

Pokémon Form:

Some Pokémon have the ability to take on different forms. At times, these differences are purely cosmetic and have no bearing on the difference in the Pokémon's stats from another; however, several Pokémon differ in stats (other than HP), type, and Ability depending on their form.

--> "Some Pokémon may appear in one of multiple, visually different forms. These differences are purely cosmetic. For variations within a Pokémon species, which do differ in more than just visuals, the 'Pokémon' entity is used to represent such a variety."

[cmmartti]

@Finrod-Amandil The docs have been updated with your suggested changes.

[rowatc]

We've just discovered pokeapi via the MEE6 Discord bot.

We're trying to understand why "!pokemon Giratina" doesn't return - which seems related to this issue.

If that's correct, is there any way we can help the indexing?

[SirSkaro]

I don't think it's quiet related to this issue, but it is similar and something that isn't well explained.

Pokemon that have multiple varieties often have a commonly perceived "default" variety. Giratina, Keldeo, and Meloetta are good examples of this. When I say those Pokemons' names, you think of a particular variety of them, and you can do things in the games to transform them into their other variety. However, their default varieties are technically named Giratina-Origin, Keldeo-Ordinary, and Meloetta-Aria, respectively. And PokeAPI indexes them by these names.

You can try it out:
/pokemon/giratina-origin and /pokemon/giratina-altered
/pokemon/keldeo-ordinary and /pokemon/keldeo-resolute
/pokemon/meloetta-aira and /pokemon/meloetta-pirouette

I understand why it is this way, and it makes sense, but it can be burdensome for developers that query by individual Pokemon by name (especially directly from user input). It is almost necessary to alias/map some Pokemon names for a good user experience. It can also be confusing that the /pokemon-species endpoint actually uses their base name for string indexing, and that both endpoints use their national pokedex number for indexing to their "default" species or form.

/pokemon/487 -> /pokemon/giratina-origin
/pokemon/647 -> /pokemon/keldeo-ordinary
/pokemon/648 -> /pokemon/meloetta-aira
/pokemon-species/giratina
/pokemon-species/keldeo
/pokemon-species/meloetta

If you were creating something like a website, aliasing/mapping wouldn't be necessary because you can always query by their pokedex number, and all forms + varieties will be served to you as a resource. All is well and fine. But in a text-chat environment like Discord, requiring a pokedex number from the user doesn't make for a good experience, and always using the name has corner cases.

I personally don't think that there is anything "wrong" with the design of the API in this regard, because I think the use case for PokeAPI is to be the engine of web-based applications. Web-based applications are often interacted with via GUIs, so you can more easily use pokedex numbers behind the scenes. But new use cases (like Discord's text-based interfacing) are popping up and the API's design requires a bit more effort for them.

I think it would be very beneficial to have a snippet of documentation explaining this indexing - including the difference between the /pokemon and /pokemon-species endpoints and a blurb for how mega evolutions can (and can't) be indexed. But I think your issue is different enough from this issue that it can be considered separate. Regardless, I think that if you made a pull requests that supported indexing a Pokemon by its base name for the /pokemon endpoint, that that would help with the indexing.

I have a Pokedex Discord bot where I have had to perform aliasing. It's open source if you want to test it out and get ideas for aliasing/mapping.