Blog·Craft·

MP is two places

MP can identify Madhya Pradesh or the Northern Mariana Islands. Keeping the country with a state code removes the ambiguity.

A two-letter state code looks like an identifier you could save on its own. MP is a good example of why that can go wrong.

With India as the country, GET /state/MP?country=IN returns these fields:

{ "state": "MP", "name": "Madhya Pradesh", "type": "state", "country": "IN" }

Change the country to the US and GET /state/MP?country=US returns:

{ "state": "MP", "name": "Northern Mariana Islands", "type": "outlying area", "country": "US" }

Both codes are valid. The country is part of what makes each one specific.

The state endpoint can resolve a unique code or name without ?country=. /state/texas, for example, has a clear answer. When the input matches multiple places, the API asks for the country instead of guessing.

For a form that already has a country picker, carry that value into the state lookup and save the two codes together. Then a record for MP remains understandable when it leaves the form and turns up in an export, a report, or another part of your application. You don't have to rediscover which country the user selected.