List jurisdictions · API reference

A page of jurisdictions, largest tier first and then by name.

Each carries its fips, its identifier list, within, the jurisdictions that contain it, and coverage, what is held for it.

Parameters

query

latnumber | null: Latitude of a point, in WGS 84. With lon, the jurisdictions whose boundary contains the point.
lonnumber | null: Longitude of the point, in WGS 84.
fipsstring | null: A US Census GEOID: 37, 37183 or 3755000. The jurisdiction with that code.
statestring | null: A US state, as NC or 37. The jurisdictions within it.
countystring | null: A US county, as 37183, or 183 with state. The jurisdictions within it.
qstring | null: A name, or the start of one. Best match first.
tier"national" | "region" | "subregion" | "local"[] | null: One of region, subregion or local. Repeatable.
typestring[] | null: The local word for the kind: county, city, town, village, township. Repeatable.
withinstring | null: A jurisdiction id. The jurisdictions inside it.
cursorstring | null: The previous page's next_cursor.
sizeinteger | null: Default 25.
totalboolean: True adds total, the count of every match, to the first page.

Responses

200: jurisdiction object; Successful Response
401: ProblemDetail; credential_missing, credential_invalid or credential_expired: send a live API key as Authorization: Bearer <key>.
402: ProblemDetail; quota_exhausted: the balance can't cover the call. Nothing was charged and nothing was returned.
403: ProblemDetail; scope_missing, person_required or entitlement_missing: this credential or plan can't do this. detail says which.
404: ProblemDetail; no_such_resource: nothing has that id.
409: ProblemDetail; version_conflict: the record changed since you read it. Read it again and resend.
422: ProblemDetail; parameter_invalid, id_malformed or a cursor code: a parameter's value isn't one this operation takes.
429: ProblemDetail; rate_limited: wait for Retry-After, then send it again. Not charged.
501: empty; not_available: no jurisdictions are published yet.

Example request

curl -G 'https://api.placestack.com/v1/jurisdiction' \
  --data-urlencode 'state=NC' \
  --data-urlencode 'size=50' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY'

Example response

{
  "object": "list",
  "data": [
    {
      "object": "jurisdiction",
      "id": "jur_01h455vb4pex5vsknk084sn02q",
      "name": "<Name>",
      "legal_name": "string",
      "type": "<Type>",
      "tier": "national",
      "country": "<Country>",
      "lifecycle_status": "<Lifecycle Status>",
      "fips": "<Fips>",
      "identifier": [
        "<Identifier>"
      ],
      "within": [
        "<Within>"
      ],
      "land_area_m2": 1,
      "water_area_m2": 1,
      "centroid": "<Centroid>",
      "coverage": "<Coverage>",
      "href": "<Href>"
    }
  ],
  "has_more": true,
  "next_cursor": "string",
  "suppressed": 0,
  "total": {
    "value": 1,
    "relation": "eq"
  }
}