Localized names

Reference data returned by the API — analytes, diagnostic tests, medicinal substances, dosage forms, health conditions, vital signs, dosing frequencies, currencies — carries a human-readable name alongside a stable machine identifier. This page describes how that name is chosen, and what to key your own records on.

Request a locale

Endpoints that return named reference data accept a locale (BCP-47, xx-XX). Casing is normalized for you, so es-us and es-US behave identically. An unrecognized or omitted locale resolves to en-US.

How name resolves

Four steps, in order:

1. Your requested locale, when a translation exists for that row.
2. Your language’s default locale — the main variant of the same language.
3. en-US, the platform fallback.
4. The row’s sysName — a stable screaming-snake identifier such as ALANINE_AMINOTRANSFERASE.

Step 2 means a Spanish client sees Spanish before it sees English, whichever Spanish market it asked for. Requesting es-MX for a row translated only into es-US returns the es-US text; fa-AF falls to fa-IR, de-CH to de-DE, pt-PT to pt-BR.

You request	No translation? Then	Then	Then
es-MX	es-US	en-US	sysName
fa-AF	fa-IR	en-US	sysName
fr-CA	fr-FR	en-US	sysName

Step 4 is reached only when a row has no translation at all, which is rare. If you are seeing sysName-shaped values in name, that is the signal — not a formatting quirk.

Behaviour changes

2026-07-30 — step 2 was added. A regional locale now falls back to its language’s main variant before English, so some responses that previously returned English now return the language you asked for. No field was added, removed or retyped.

2026-07-29 — a row with no translation in the requested locale previously skipped the English step and returned its sysName directly. Non-English clients now receive the English name in that case.

Both changes only ever make name more readable. Neither affects sysName, which is what you should be keying on.

Key on sysName, display name

sysName is stable across locales and releases — it is the correct join key for your own storage and for reconciling records between systems. name is a display string: it varies by locale, and it changes as translations are added. Do not parse it, match on it, or store it as an identifier.

{
  "id": 42,
  "sysName": "ALANINE_AMINOTRANSFERASE",
  "name": "Alanine aminotransférase"
}

Animal names are never localized

Everything above concerns reference data — common nouns with a translation per locale. An individual animal’s callName and registeredName are proper nouns and take no part in it: they have no locale variants, no en-US fallback and no sysName. Requesting a different locale does not change them.

What an animal carries instead is one name stored in two spellings:

Field	Meaning
callName	The name as its owner writes it, in that name’s own script. Canonical.
callNameRomanized	The Latin spelling of the same name. null when callName is already Latin.
callNameLocaleCode	The script/language of the name (e.g. fa-IR) — not a viewer locale.

registeredName has the identical trio. callNameLocaleCode is metadata about the string, so do not feed it into your locale negotiation — an animal named برف is named برف for a reader in Tokyo and a reader in Toronto alike.

{
  "callName": "برف",
  "callNameRomanized": "Barf",
  "callNameLocaleCode": "fa-IR",
  "registeredName": "Barf of Alborz",
  "registeredNameRomanized": null
}

Display callName; fall back to callNameRomanized only when you cannot render the script. Both spellings are matched by the animal search, so a Latin-keyboard query for Barf finds the animal above.

Added 2026-07-29

The six fields are additive and nullable. callName and registeredName keep their exact former meaning and are unchanged for animals whose names are already Latin, which is most of them.

Slugs are per-locale

URL slugs are not subject to the fallback above. A slug is unique within one locale, so a slug minted for en-US resolves only under en-US. Request a resource by slug using the same locale that produced the slug; use sysName when you need a locale-independent lookup.