Blog·Craft·

The native name is a sibling, not the default

Postal lookups put the readable name in the main field and keep a different native form beside it.

Reading a city name shouldn't require a fallback expression in every application. The postal response used to put the native name first and leave callers to choose an English alternative when they wanted one. That made a simple label more work than it needed to be.

The order is now consistent: the main field contains English or an official romanization when the source provides one, and the native form otherwise. A different native form sits beside it.

Here are the name fields from GET /postal/1000001?country=JP:

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

For an ordinary label, read city. If you also want to show the original script, read city_local. The same pattern applies to the state and district names.

A _local field is null when the native form is missing or would repeat the primary name. It doesn't mean the place has no local name, and a non-null value isn't a translation produced on request.

There's no ?lang= switch. The response keeps both source forms available so your display can use them without changing the lookup.