Jurisdictions normalize

Heuristic

jurisdictions_normalize

Best-effort — fuzzy, approximate, or inferred; check the confidence score.

Normalize a jurisdiction code or full name to its canonical record. Returns code, name, iso_code, type (country/state/territory/district/armed_forces_postal), parent_code, and matched_by. Accepts codes (case-insensitive), full names, and curated common variants ('USA', 'UK', 'United States of America', 'Czechia' — matched_by='alias' at 1.0). Optional type and parent_code filters disambiguate collisions. Confidence 1.0 on unambiguous match, 0.85 when ambiguous; when exact matching misses, a conservative fuzzy fallback catches small typos (0.7) and unique name prefixes (0.8) with matched_by='fuzzy'; 0.0 when no match. Processing multiple inputs? Use `jurisdictions_normalize_batch` to do up to 1000 in one call.

Parameters

valuestringrequired

Jurisdiction code or full name to normalize to a canonical record.

typestringoptional

Filter by jurisdiction type. Valid values: country, state, territory, district, armed_forces_postal. When omitted, all types are searched and the best match is returned (US-scoped types preferred when ambiguous).

parent_codestringoptional

Filter by parent code (e.g. 'US' to restrict to US states/territories/DC). Case-insensitive.

Call it

curl -X POST https://api.snipget.ai/v1/jurisdictions/normalize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"value":"California","parent_code":"US"}'

The Batch tab sends up to 1000 inputs in one call via /v1/jurisdictions/normalize/batch.

Example response

{
  "code": "CA",
  "name": "California",
  "iso_code": "US-CA",
  "type": "state",
  "parent_code": "US",
  "matched_by": "name"
}

FAQ

What is this for?

It turns messy input like california, calif, ca, or united states into one clean, official record with the standard code, full name, and ISO code. Perfect for tidying a spreadsheet column where people typed the same place five different ways.

Can it take both codes and full names?

Yes. It accepts a 2-letter or short code (case does not matter) or the full name (case does not matter), tries the code first, then the name, then a curated set of common variants like USA, UK, or United States of America (matched_by comes back alias for those). The matched_by field tells you which step matched.

How is this different from Validate?

Validate just says yes or no plus the type. Normalize returns the whole canonical record: code, name, iso_code, type, and parent_code. Use Validate to check, use Normalize to clean and standardize.

Is the answer exact?

Exact matches are deterministic and authoritative: a unique code, full-name, or curated-alias match returns confidence 1.0, and an ambiguous code with no filter returns 0.85 (add parent_code or type to pin it down). When nothing matches exactly, a conservative fuzzy fallback tries a small typo ('Californa', confidence 0.7) or a unique name prefix ('calif', confidence 0.8) and sets matched_by to 'fuzzy' - treat those as review-worthy, not authoritative.

What if it cannot find the place?

It returns confidence 0 with every field set to null and a reason in the trace, never an error. So a no-match row in your batch is easy to spot and skip.

Full API reference (schemas, error codes) →