Handling warnings

The warnings field on every response is a list of advisories about the lookup. They’re not errors — the rate is still authoritative — but they tell you something the caller should know.

Items come in two shapes: some are plain strings (short advisories, e.g. about a fallback resolution), and some are structured objects carrying a code you can branch on.

Most common structured warning today:

place_input_mismatch — the customer-supplied city name doesn’t match the actual jurisdiction at the address. Example: the customer typed “Frisco” but the address resolves to unincorporated Denton County. It carries code, a severity, the customer_input_place, and the resolved_place_name (also exposed as authoritative):

{
  "code": "place_input_mismatch",
  "severity": "info",
  "customer_input_place": "Frisco",
  "resolved_place_name": "Denton County (unincorporated)"
}

Handle both shapes by checking whether the item is an object first:

for w in response["meta"]["warnings"]:      # simple mode; use response["warnings"] in full mode
    if isinstance(w, dict):
        if w.get("code") == "place_input_mismatch":
            print(f"⚠ input '{w['customer_input_place']}' resolved to "
                  f"'{w['resolved_place_name']}'")
    else:
        print(f"⚠ {w}")                     # plain-string advisory

The set of warning codes is small and stable; new ones are added as the API surfaces more edge cases.

Full content coming soon — including a complete warning-code registry and recommended caller-side handling for each.