Testing location data with edge cases, not just happy paths
An address in a well mapped city center tells you almost nothing about how your system handles a rural route, a disputed border, or a query near the poles. Test the hard cases deliberately.
ISO 3166-1 and 3166-2 codes, and where they get confusing
ISO 3166-1 assigns a standard two-letter code to every recognized country, and it is the closest thing location software has to a universal, stable identifier for "which country." DE for Germany, JP for Japan, BR for Brazil. It is widely used precisely because it is short, stable, and unambiguous once you know the standard, which is exactly why our postal code lookup requires it alongside a code rather than a free-text country name.
ISO 3166-2 extends this one level down, assigning codes to subdivisions within a country, states, provinces, regions, depending on how that country organizes itself. A US state, a Canadian province, and a Japanese prefecture are all represented this way, each as a code that combines the country prefix with a subdivision identifier. This is useful anywhere you need a stable identifier for "which region within a country" that does not depend on matching free-text names that can be spelled, abbreviated, or translated differently across data sources.
Confusion usually shows up in a few predictable places. Free-text country names create the most obvious mismatches, since "United States," "USA," "U.S.," and "America" all mean the same thing to a person but not automatically to code expecting an exact string match, which is exactly the ambiguity the two-letter code exists to remove. Subdivision structures also vary enormously between countries, some divide neatly into a small number of states or provinces, while others use several administrative tiers, and mapping user-facing labels like "state," "province," or "county" onto ISO 3166-2 codes is not a one-to-one exercise across every country.
Another common source of confusion is conflating a country's top-level domain with its ISO code. They frequently match, .de and DE, but not always, and treating a domain suffix as a reliable stand-in for the country code will eventually produce a wrong result for the exceptions.
The practical guidance is to store and pass ISO 3166-1 codes rather than free-text country names wherever your system talks to another system, including ours, and to use ISO 3166-2 codes for subdivisions whenever you need a stable identifier rather than a display label. Reserve human-readable names for what your users actually see on screen, and keep the codes underneath for anything that needs to match reliably.
Our postal code lookup takes an ISO 3166-1 alpha-2 country code alongside the postal code itself, precisely so the request is unambiguous regardless of how a country's name might otherwise be written.