Suggest matches for typed text · API reference

A short list of suggestions, governments first, then addresses and parcel numbers that start with what was typed.

Each carries the query to send to reach it and, where the thing already has a path, its href. Free.

Parameters

query

qrequiredstring: What has been typed so far.
kind"address" | "parcel" | "jurisdiction"[] | null: Only these kinds. One of address, parcel or jurisdiction. Repeatable. Every kind when omitted.
jurisdictionstring[] | null: A jurisdiction id. Only addresses and parcels within it. Repeatable.
fipsstring[] | null: A US Census GEOID, 2 digits for a state or 5 for a county. Only addresses and parcels within it. Repeatable.
sizeinteger: How many to return. Defaults to 8.

Responses

200: suggestion 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: nothing is published to suggest from yet.

Example request

curl -G 'https://api.placestack.com/v1/suggestion' \
  --data-urlencode 'q=value' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "object": "suggestion",
      "kind": "address",
      "label": "<Label>",
      "detail": "string",
      "query": {
        "key": "string"
      },
      "href": "string"
    }
  ],
  "has_more": true,
  "next_cursor": "string",
  "suppressed": 0,
  "total": {
    "value": 1,
    "relation": "eq"
  }
}