API reference

Resolve regions

Resolve ISO 3166-2 administrative regions for coordinates. The response uses the same region entries as List regions.

1 credit per successful call · Authentication and account rate limit apply.

POST /v1/resolve-region

Request body

application/json · Up to 64 KiB. Unknown fields are rejected. Send your key in x-api-key.

  • boundingBox BoundingBox
    Nested fields
    • maxLat number

      Northern latitude in degrees.

    • maxLon number

      Eastern longitude in degrees.

    • minLat number

      Southern latitude in degrees.

    • minLon number

      Western longitude in degrees.

  • lat number

    Latitude in degrees, from -90 to 90. Omission uses the protobuf default of 0.

  • lon number

    Longitude in degrees, from -180 to 180. Omission uses the protobuf default of 0.

Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

  • regions Region[]

    Countries and administrative regions known to the index.

    Nested fields
    • adminCode string

      ISO 3166-2 administrative region code.

    • adminLevel integer

      Administrative level.

      Range: 0–4294967295.

    • countryCode string

      ISO 3166-1 alpha-2 country code.

    • countryName string

      Country name.

    • enName string

      English region name.

    • localName string

      Local region name.

    • parentAdminCode string

      Parent administrative region code, when available.

Errors

HTTPCodeMeaning
400invalid_argumentInvalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.
401unauthenticatedThe API key is missing, invalid, expired or revoked.
403permission_deniedA browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.
404not_foundThe suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again.
429resource_exhaustedThe per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.
503unavailableThe API is starting or the geocoder is temporarily unavailable.
Error handling and retries →