Documentation menu

API reference

Reference

Covers vocabulary and service. Every parameter, response and example below is generated from the contract.

The facts that belong to every operation rather than to this group, the refusal shape, the cursor rules, the filters and the credential each call accepts, are the other pages under API. What a field means is under Get started.

Operations: 4
Tags: 2
Need a credential: 2
Public: 2

vocabulary

2 operations

Every closed vocabulary, the land-use hierarchy, and the rubrics behind confidence numbers.

GET/vocabularyAPI key

Every controlled vocabulary

Operation ID list_vocabulary_vocabulary_get

Parameters

No parameters.

Responses

200: Listing_VocabularySummary_; Successful Response
401: empty; No usable credential.
402: ErrorResponse; quota_exhausted: out of credit. Credit is prepaid and the balance cannot go below zero, so add credit rather than retrying.
403: ErrorResponse; entitlement_missing: the plan does not cover this operation.
404: ErrorResponse; No such id. The only meaning of 404.
422: ErrorResponse; The request cannot be answered as asked. The code says why.
429: ErrorResponse; rate_limited, with Retry-After.
501: ErrorResponse; not_available: this operation does not answer yet.

Example request

curl -X GET 'http://localhost:8000/vocabulary' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "request": {
    "path": "<Path>",
    "param": {},
    "dry_run": false
  },
  "meta": {
    "contract_date": "2026-09-13",
    "vocabulary_version": "<Vocabulary Version>",
    "request_id": "req_01h455vb4pex5vsknk084sn02q",
    "api_version": "v1",
    "answer_id": "ans_01h455vb4pex5vsknk084sn02q",
    "answer_through": 1,
    "unit": {
      "key": "string"
    },
    "cost": "<Cost>"
  },
  "item": [
    {
      "name": "<Name>",
      "kind": "enum",
      "description": "<Description>",
      "version": "<Version>",
      "entry_count": 1,
      "href": "<Href>"
    }
  ],
  "page": {
    "size": 1,
    "next_cursor": "string",
    "indeterminate": 0,
    "total": "<envelope__Total>"
  },
  "as_of": {
    "resolved": "<Interval>",
    "timezone": "<Timezone>",
    "basis": "requested",
    "known_as_of": "2026-09-13T12:00:00Z",
    "known_as_of_basis": "requested",
    "requested": "string",
    "earliest_retained": {
      "key": "2026-09-13"
    },
    "constant": true,
    "segment_count": 1
  },
  "notice": [
    {
      "code": "as_of_interval_spans_change",
      "severity": "info",
      "detail": "<Detail>",
      "count": 1,
      "subject": [
        "string"
      ]
    }
  ]
}

GET/vocabulary/{name}API key

One vocabulary, rubric or land-use hierarchy

Operation ID get_vocabulary_vocabulary__name__get

Parameters

path

namerequiredstring: status, control_type, use, geocode_precision, expected_miss_rate, ...

query

qstring | null: Label match, for use.
parentstring | null: No description.
jurisdictionstring | null: For use: include this town's own terms.
platform"attom" | "lbcs" | "naics" | "regrid" | null: With include=crosswalk.
includestring | null: Comma-separated: crosswalk, local_term.
as_ofstring | null: Valid time: the law in force then. Default now, in the jurisdiction's timezone. 2024-06-30, 2024-06-30T14:00:00-04:00, from:2023-01-01 to:2024-12-31, or last 90 days. An interval returns segment[], never a winner.

Responses

200: Single_Vocabulary_; Successful Response
401: empty; No usable credential.
402: ErrorResponse; quota_exhausted: out of credit. Credit is prepaid and the balance cannot go below zero, so add credit rather than retrying.
403: ErrorResponse; entitlement_missing: the plan does not cover this operation.
404: ErrorResponse; No such id. The only meaning of 404.
422: ErrorResponse; The request cannot be answered as asked. The code says why.
429: ErrorResponse; rate_limited, with Retry-After.
501: ErrorResponse; not_available: this operation does not answer yet.

Example request

curl -X GET 'http://localhost:8000/vocabulary/name_123?jurisdiction=value&as_of=2026-09-13' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "request": {
    "path": "<Path>",
    "param": {},
    "dry_run": false
  },
  "meta": {
    "contract_date": "2026-09-13",
    "vocabulary_version": "<Vocabulary Version>",
    "request_id": "req_01h455vb4pex5vsknk084sn02q",
    "api_version": "v1",
    "answer_id": "ans_01h455vb4pex5vsknk084sn02q",
    "answer_through": 1,
    "unit": {
      "key": "string"
    },
    "cost": "<Cost>"
  },
  "item": {
    "name": "<Name>",
    "kind": "enum",
    "description": "<Description>",
    "version": "<Version>",
    "entry_count": 1,
    "href": "<Href>",
    "entry": [
      "<VocabularyEntry>"
    ]
  },
  "as_of": {
    "resolved": "<Interval>",
    "timezone": "<Timezone>",
    "basis": "requested",
    "known_as_of": "2026-09-13T12:00:00Z",
    "known_as_of_basis": "requested",
    "requested": "string",
    "earliest_retained": {
      "key": "2026-09-13"
    },
    "constant": true,
    "segment_count": 1
  },
  "notice": [
    {
      "code": "as_of_interval_spans_change",
      "severity": "info",
      "detail": "<Detail>",
      "count": 1,
      "subject": [
        "string"
      ]
    }
  ],
  "coverage": {
    "jurisdiction": "jur_01h455vb4pex5vsknk084sn02q",
    "layer": {
      "key": "<CoverageLayer>"
    },
    "href": "<Href>"
  }
}

service

2 operations

Service identity and health.

GET/Public

Identify the service

Say what this is. Proves the service is reachable.

Operation ID root

Parameters

No parameters.

Responses

200: Service; Successful Response

Example request

curl -X GET 'http://localhost:8000/'

Example response

{
  "service": "<Service>",
  "version": "<Version>",
  "status": "<Status>",
  "docs": "<Docs>",
  "issuer": "<Issuer>"
}

GET/healthPublic

Check the service's health

Report whether the service can reach Postgres. Reads no tables.

Operation ID health

Parameters

No parameters.

Responses

200: Health; Successful Response

Example request

curl -X GET 'http://localhost:8000/health'

Example response

{
  "service": "<Service>",
  "database": "<Database>",
  "schema_name": "<Schema Name>",
  "redis": "<Redis>",
  "redis_prefix": "<Redis Prefix>",
  "elasticsearch": "<Elasticsearch>",
  "index_prefix": "<Index Prefix>",
  "signing_key": "<Signing Key>"
}

The document

Everything above is read from OpenAPI 3.1.0 version 0.0.0. When the contract changes, this page follows.

Download the OpenAPI document

Account

26 operations: identity, onboarding, auth, entitlement, usage, billing, oauth.