Regional Variant Evolution Chains - PokeAPI v3 Feature Request

[joereg4]

Problem Statement

The current PokeAPI v2 structure has a fundamental limitation that prevents proper representation of regional variant evolution chains. While the API can handle regional evolution locks (e.g., Meowth → Perrserker requiring Galar region), it cannot represent form-specific evolution chains (e.g., Rattata-Alola → Raticate-Alola).

Current PokeAPI v2 Structure

Data Architecture

• pokemon_species.csv: Contains species definitions (e.g., rattata, raticate)
• pokemon.csv: Contains individual Pokemon forms (e.g., rattata-alola, raticate-alola)
• pokemon_evolution.csv: Defines evolution chains at the species level

Key Limitation

Regional variants are represented as forms of existing species, not separate species:

pokemon_species.csv:
- rattata (species_id: 19)
- raticate (species_id: 20)

pokemon.csv:
- rattata (pokemon_id: 19, species_id: 19) - base form
- rattata-alola (pokemon_id: 10091, species_id: 19) - Alolan form
- raticate (pokemon_id: 20, species_id: 20) - base form  
- raticate-alola (pokemon_id: 10092, species_id: 20) - Alolan form

The Problem

What Works in v2

✅ Regional evolution locks: Meowth → Perrserker (Galar region only)

• This works because both meowth and perrserker exist as separate species
• The evolution chain can be locked to a specific region

What Doesn't Work in v2

❌ Regional variant evolution chains: Rattata-Alola → Raticate-Alola

• rattata-alola and raticate-alola are forms of existing species, not separate species
• Evolution chains are defined at the species level, not the form level
• There's no mechanism to have different evolution chains for different forms of the same species

Real-World Examples

Example 1: Rattata Evolution

Current v2 behavior:

• rattata → raticate (works everywhere)
• rattata-alola → raticate-alola (cannot be represented)

What users expect:

• Alolan Rattata should evolve into Alolan Raticate
• Kanto Rattata should evolve into Kanto Raticate
• These should be separate evolution chains

Example 2: Meowth Evolution

Current v2 behavior:

• meowth → persian (works everywhere)
• meowth → perrserker (Galar region only)

What works:

• Regional evolution locks work because Perrserker is a separate species
• The evolution chain can be restricted to Galar region

What doesn't work:

• Cannot represent meowth-alola → persian-alola as a separate chain
• Cannot represent meowth-galar → perrserker as a separate chain

Technical Constraints

Current Evolution Chain Structure

{
  "evolution_chain": {
    "id": 19,
    "chain": {
      "species": {"name": "rattata"},
      "evolves_to": [{
        "species": {"name": "raticate"},
        "evolution_details": [{
          "min_level": 20,
          "trigger": {"name": "level-up"}
        }]
      }]
    }
  }
}

What's Missing

• No way to specify form-specific evolution chains
• No way to represent rattata-alola → raticate-alola
• No way to have different evolution conditions for different forms

Proposed v3 Solution

Option 1: Form-Specific Evolution Chains

• Add form-specific evolution chains alongside species-level chains
• Allow evolution chains to reference specific Pokemon forms
• Maintain backward compatibility with existing species-level chains

Option 2: Enhanced Evolution Details

• Extend evolution details to include form requirements
• Add form-specific evolution conditions
• Allow evolution chains to specify which forms can evolve into which forms

Option 3: Hybrid Approach

• Keep species-level evolution chains for backward compatibility
• Add form-specific evolution chains as an additional layer
• Allow API consumers to choose which level of detail they need

Impact Assessment

Affected Pokemon

• Alolan variants: Rattata, Raticate, Sandshrew, Sandslash, Vulpix, Ninetales, Diglett, Dugtrio, Meowth, Persian, Geodude, Graveler, Golem, Grimer, Muk, Exeggutor, Marowak
• Galarian variants: Meowth, Ponyta, Rapidash, Slowpoke, Slowbro, Farfetch'd, Weezing, Mr. Mime, Articuno, Zapdos, Moltres, Slowking, Corsola, Zigzagoon, Linoone, Darumaka, Darmanitan, Yamask, Stunfisk
• Hisuian variants: Growlithe, Arcanine, Voltorb, Electrode, Typhlosion, Qwilfish, Sneasel, Samurott, Lilligant, Basculin, Zorua, Zoroark, Braviary, Sliggoo, Goodra, Avalugg, Decidueye
• Paldean variants: Tauros, Wooper, Clodsire

API Endpoints Affected

• /api/v2/pokemon-species/{id}/
• /api/v2/evolution-chain/{id}/
• /api/v2/pokemon/{id}/

Implementation Considerations

Backward Compatibility

• Existing species-level evolution chains must continue to work
• API consumers should not be forced to migrate immediately
• Gradual migration path should be provided

Data Structure Changes

• New tables/fields for form-specific evolution chains
• Migration strategy for existing data
• Build process updates to handle form-specific chains

Performance Impact

• Additional database queries for form-specific evolution chains
• Caching strategies for complex evolution trees
• API response size considerations

Conclusion

The current PokeAPI v2 structure cannot properly represent regional variant evolution chains due to its species-centric design. This is a fundamental limitation that requires a significant architectural change to resolve.

Recommendation: This should be implemented as a PokeAPI v3 feature with a new evolution chain system that can handle form-specific evolution paths while maintaining backward compatibility with the existing species-based system.