Blog·Craft·

The native name is a sibling, not the default

Postal names come back readable first. The original-script form sits next to it when it differs.

Call /postal/1000001?country=JP and the city comes back as Chiyoda Ku. Readable immediately.

{
  "postal": "1000001",
  "city": "Chiyoda Ku",
  "city_local": "千代田区",
  "state_name": "Tokyo To",
  "state_name_local": "東京都",
  "district_name": "Chiyoda",
  "district_name_local": "千代田",
  "country": "JP"
}

city_local, state_name_local, and district_name_local sit next to the primary field. Same shape everywhere. city_local is a sibling of city.

One field to read first

No ?lang= parameter. city is always the field to read: English or an official romanization when the source has one, the source's own form otherwise. city_local is null when it would duplicate city. Non-null means a genuinely different native form.

{ "city": "Paris", "city_local": null, "country": "FR" }
{ "city": "Charlotte", "city_local": null, "country": "US" }
{ "city": "Chiyoda Ku", "city_local": "千代田区", "country": "JP" }

Read data.city and every country returns something printable. Reach for city_local when you want the original script on a shipping label or a localized display.

Try it

Call a JP postal code and print city next to city_local. Same place, two scripts.