Documentation menu
API reference

Change and coverage

Covers change_event, alert, webhook and coverage. 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
16
Tags
4
Need a credential
16
Public
0

change_event

2 operations

The append-only change feed, as JSON or a live stream.

GET/change_eventAPI key

What changed, cited on both sides

since=N&known_as_of=T returns exactly the events with seq > N detected by T, in seq order, forever.

Operation ID list_change_event_change_event_get

Parameters

query

sincerequiredinteger
The seq watermark you hold. Required: the feed is a replay contract.
untilinteger | null
No description.
known_as_ofstring | null
Knowledge time: the answer we would have given then. Default now. Same grammar as as_of.
layer"authority" | "district" | "district_map" | "overlay"[]
No description.
kind"adoption" | "amendment" | "repeal" | "map_change"[]
backfill is a newly found old rule, not a new change.
cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.
regionstring | null
A saved rgn_ region, or a statistical area such as a CBSA (sta_ id). Membership resolves at as_of.
jurisdictionstring[]
A jur_ id or fips_key. Repeatable.
statestring | null
Two-letter postal code or two-digit FIPS.
countystring | null
County FIPS, 5 digits, or a county's jur_ id.
geometrystring | null
WKT or GeoJSON. Jurisdictions that intersect it.
buffernumber | null
Feet around geometry.

header

Last-Event-IDstring | null
No description.

Responses

200
Collection_ChangeEvent_
JSON by default. With Accept: text/event-stream, a resumable stream: id: is the seq, event: is the layer, and Last-Event-ID resumes exclusively.
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/change_event?since=value' \
  -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": [
    {
      "id": "chg_01h455vb4pex5vsknk084sn02q",
      "seq": 1,
      "kind": "adoption",
      "layer": "authority",
      "subject": "<ChangeSubject>",
      "jurisdiction": "<JurisdictionRef>",
      "effective_date": "2026-09-13",
      "detected_at": "2026-09-13T12:00:00Z",
      "field_path": "string",
      "previous": "<ChangeSide>",
      "current": "<ChangeSide>",
      "adopted_on": "2026-09-13",
      "ordinance": "ord_01h455vb4pex5vsknk084sn02q"
    }
  ],
  "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"
      ]
    }
  ],
  "coverage": {
    "jurisdiction": "jur_01h455vb4pex5vsknk084sn02q",
    "layer": {
      "key": "<CoverageLayer>"
    },
    "href": "<Href>"
  }
}
GET/change_event/{change_event}API key

One change

Operation ID get_change_event_change_event__change_event__get

Parameters

path

change_eventrequiredstring
A chg_ id.

Responses

200
Single_ChangeEvent_
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/change_event/change_event_123' \
  -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": {
    "id": "chg_01h455vb4pex5vsknk084sn02q",
    "seq": 1,
    "kind": "adoption",
    "layer": "authority",
    "subject": "<ChangeSubject>",
    "jurisdiction": "<JurisdictionRef>",
    "effective_date": "2026-09-13",
    "detected_at": "2026-09-13T12:00:00Z",
    "field_path": "string",
    "previous": "<ChangeSide>",
    "current": "<ChangeSide>",
    "adopted_on": "2026-09-13",
    "ordinance": "ord_01h455vb4pex5vsknk084sn02q"
  },
  "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>"
  }
}

alert

6 operations

Stored predicates over the change feed.

GET/alertAPI key

Your alerts

Operation ID list_alert_alert_get

Parameters

query

cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.

Responses

200
Listing_Alert_
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/alert?size=50' \
  -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>",
      "predicate": {},
      "trigger": [
        "entry"
      ],
      "id": "alr_01h455vb4pex5vsknk084sn02q",
      "predicate_version": 1,
      "monitoring_started_at": "2026-09-13T12:00:00Z",
      "unread_count": 1,
      "created_at": "2026-09-13T12:00:00Z",
      "href": "<Href>",
      "channel": [
        "<Channel>"
      ],
      "schedule": "string",
      "timezone": "string",
      "end_time": "2026-09-13T12:00:00Z",
      "enabled": true
    }
  ],
  "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"
      ]
    }
  ]
}
POST/alertAPI key

Watch for changes

Operation ID post_alert_alert_post

Parameters

header

Idempotency-Keystring | null
Replays the first response for 24 hours.

Responses

201
Single_Alert_
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 POST 'http://localhost:8000/alert' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<Name>",
  "predicate": {},
  "trigger": [
    "entry"
  ],
  "channel": [
    {
      "type": "webhook",
      "webhook": "whk_01h455vb4pex5vsknk084sn02q",
      "target": "string"
    }
  ],
  "schedule": "string",
  "timezone": "string",
  "end_time": "2026-09-13T12:00:00Z",
  "enabled": true
}'

Request body

AlertBody

{
  "name": "<Name>",
  "predicate": {},
  "trigger": [
    "entry"
  ],
  "channel": [
    {
      "type": "webhook",
      "webhook": "whk_01h455vb4pex5vsknk084sn02q",
      "target": "string"
    }
  ],
  "schedule": "string",
  "timezone": "string",
  "end_time": "2026-09-13T12:00:00Z",
  "enabled": true
}

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>",
    "predicate": {},
    "trigger": [
      "entry"
    ],
    "id": "alr_01h455vb4pex5vsknk084sn02q",
    "predicate_version": 1,
    "monitoring_started_at": "2026-09-13T12:00:00Z",
    "unread_count": 1,
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "channel": [
      "<Channel>"
    ],
    "schedule": "string",
    "timezone": "string",
    "end_time": "2026-09-13T12:00:00Z",
    "enabled": true
  },
  "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>"
  }
}
GET/alert/{alert}API key

One alert

Operation ID get_alert_alert__alert__get

Parameters

path

alertrequiredstring
An alr_ id.

Responses

200
Single_Alert_
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/alert/alert_123' \
  -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>",
    "predicate": {},
    "trigger": [
      "entry"
    ],
    "id": "alr_01h455vb4pex5vsknk084sn02q",
    "predicate_version": 1,
    "monitoring_started_at": "2026-09-13T12:00:00Z",
    "unread_count": 1,
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "channel": [
      "<Channel>"
    ],
    "schedule": "string",
    "timezone": "string",
    "end_time": "2026-09-13T12:00:00Z",
    "enabled": true
  },
  "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>"
  }
}
PATCH/alert/{alert}API key

Change an alert

Editing the predicate versions it, and replays say which version they matched against.

Operation ID patch_alert_alert__alert__patch

Parameters

path

alertrequiredstring
An alr_ id.

header

If-Matchstring | null
The ETag you last read. A stale one is 409.

Responses

200
Single_Alert_
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 PATCH 'http://localhost:8000/alert/alert_123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "predicate": {},
  "trigger": [
    "entry"
  ],
  "channel": [
    "<Channel>"
  ],
  "schedule": "string"
}'

Request body

AlertPatch

{
  "name": "string",
  "predicate": {},
  "trigger": [
    "entry"
  ],
  "channel": [
    "<Channel>"
  ],
  "schedule": "string"
}

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>",
    "predicate": {},
    "trigger": [
      "entry"
    ],
    "id": "alr_01h455vb4pex5vsknk084sn02q",
    "predicate_version": 1,
    "monitoring_started_at": "2026-09-13T12:00:00Z",
    "unread_count": 1,
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "channel": [
      "<Channel>"
    ],
    "schedule": "string",
    "timezone": "string",
    "end_time": "2026-09-13T12:00:00Z",
    "enabled": true
  },
  "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>"
  }
}
DELETE/alert/{alert}API key

Stop an alert

Operation ID delete_alert_alert__alert__delete

Parameters

path

alertrequiredstring
An alr_ id.

header

If-Matchstring | null
The ETag you last read. A stale one is 409.

Responses

204
empty
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 DELETE 'http://localhost:8000/alert/alert_123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'
GET/alert/{alert}/change_eventAPI key

What an alert has matched

Operation ID list_alert_change_event_alert__alert__change_event_get

Parameters

path

alertrequiredstring
An alr_ id.

query

sinceinteger
No description.
known_as_ofstring | null
Knowledge time: the answer we would have given then. Default now. Same grammar as as_of.
cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.

Responses

200
Collection_ChangeEvent_
JSON by default. With Accept: text/event-stream, a resumable stream: id: is the seq, event: is the layer, and Last-Event-ID resumes exclusively.
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/alert/alert_123/change_event?size=50' \
  -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": [
    {
      "id": "chg_01h455vb4pex5vsknk084sn02q",
      "seq": 1,
      "kind": "adoption",
      "layer": "authority",
      "subject": "<ChangeSubject>",
      "jurisdiction": "<JurisdictionRef>",
      "effective_date": "2026-09-13",
      "detected_at": "2026-09-13T12:00:00Z",
      "field_path": "string",
      "previous": "<ChangeSide>",
      "current": "<ChangeSide>",
      "adopted_on": "2026-09-13",
      "ordinance": "ord_01h455vb4pex5vsknk084sn02q"
    }
  ],
  "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"
      ]
    }
  ],
  "coverage": {
    "jurisdiction": "jur_01h455vb4pex5vsknk084sn02q",
    "layer": {
      "key": "<CoverageLayer>"
    },
    "href": "<Href>"
  }
}

webhook

7 operations

Delivery endpoints, their logs and test deliveries.

GET/webhookAPI key

Your webhooks

Operation ID list_webhook_webhook_get

Parameters

query

cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.

Responses

200
Listing_Webhook_
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/webhook?size=50' \
  -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": [
    {
      "url": "<Url>",
      "secret_ref": "<Secret Ref>",
      "event_type": [
        "change_event"
      ],
      "id": "whk_01h455vb4pex5vsknk084sn02q",
      "secret_fingerprint": "<Secret Fingerprint>",
      "retry_policy": "<RetryPolicy>",
      "created_at": "2026-09-13T12:00:00Z",
      "href": "<Href>",
      "alert": [
        "alr_01h455vb4pex5vsknk084sn02q"
      ],
      "active": true
    }
  ],
  "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"
      ]
    }
  ]
}
POST/webhookAPI key

Add a delivery endpoint

Operation ID post_webhook_webhook_post

Parameters

header

Idempotency-Keystring | null
Replays the first response for 24 hours.

Responses

201
Single_Webhook_
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 POST 'http://localhost:8000/webhook' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "<Url>",
  "secret_ref": "<Secret Ref>",
  "event_type": [
    "change_event"
  ],
  "alert": [
    "alr_01h455vb4pex5vsknk084sn02q"
  ],
  "active": true
}'

Request body

WebhookBody

{
  "url": "<Url>",
  "secret_ref": "<Secret Ref>",
  "event_type": [
    "change_event"
  ],
  "alert": [
    "alr_01h455vb4pex5vsknk084sn02q"
  ],
  "active": true
}

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": {
    "url": "<Url>",
    "secret_ref": "<Secret Ref>",
    "event_type": [
      "change_event"
    ],
    "id": "whk_01h455vb4pex5vsknk084sn02q",
    "secret_fingerprint": "<Secret Fingerprint>",
    "retry_policy": "<RetryPolicy>",
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "alert": [
      "alr_01h455vb4pex5vsknk084sn02q"
    ],
    "active": true
  },
  "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>"
  }
}
GET/webhook/{webhook}API key

One webhook

Operation ID get_webhook_webhook__webhook__get

Parameters

path

webhookrequiredstring
A whk_ id.

Responses

200
Single_Webhook_
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/webhook/webhook_123' \
  -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": {
    "url": "<Url>",
    "secret_ref": "<Secret Ref>",
    "event_type": [
      "change_event"
    ],
    "id": "whk_01h455vb4pex5vsknk084sn02q",
    "secret_fingerprint": "<Secret Fingerprint>",
    "retry_policy": "<RetryPolicy>",
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "alert": [
      "alr_01h455vb4pex5vsknk084sn02q"
    ],
    "active": true
  },
  "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>"
  }
}
PATCH/webhook/{webhook}API key

Change a webhook

Operation ID patch_webhook_webhook__webhook__patch

Parameters

path

webhookrequiredstring
A whk_ id.

header

If-Matchstring | null
The ETag you last read. A stale one is 409.

Responses

200
Single_Webhook_
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 PATCH 'http://localhost:8000/webhook/webhook_123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "string",
  "secret_ref": "string",
  "event_type": [
    "change_event"
  ],
  "alert": [
    "alr_01h455vb4pex5vsknk084sn02q"
  ],
  "active": true
}'

Request body

WebhookPatch

{
  "url": "string",
  "secret_ref": "string",
  "event_type": [
    "change_event"
  ],
  "alert": [
    "alr_01h455vb4pex5vsknk084sn02q"
  ],
  "active": true
}

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": {
    "url": "<Url>",
    "secret_ref": "<Secret Ref>",
    "event_type": [
      "change_event"
    ],
    "id": "whk_01h455vb4pex5vsknk084sn02q",
    "secret_fingerprint": "<Secret Fingerprint>",
    "retry_policy": "<RetryPolicy>",
    "created_at": "2026-09-13T12:00:00Z",
    "href": "<Href>",
    "alert": [
      "alr_01h455vb4pex5vsknk084sn02q"
    ],
    "active": true
  },
  "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>"
  }
}
DELETE/webhook/{webhook}API key

Remove a webhook

Operation ID delete_webhook_webhook__webhook__delete

Parameters

path

webhookrequiredstring
A whk_ id.

header

If-Matchstring | null
The ETag you last read. A stale one is 409.

Responses

204
empty
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 DELETE 'http://localhost:8000/webhook/webhook_123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'
GET/webhook/{webhook}/deliveryAPI key

The delivery log

Operation ID list_delivery_webhook__webhook__delivery_get

Parameters

path

webhookrequiredstring
A whk_ id.

query

state"pending" | "delivered" | "failed" | "dead_lettered"[]
No description.
event_type"change_event" | "alert_match" | "inquiry_event" | "extract_ready"[]
No description.
sinceinteger | null
No description.
cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.

Responses

200
Listing_Delivery_
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/webhook/webhook_123/delivery?state=NC&size=50' \
  -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": [
    {
      "seq": 1,
      "event_type": "change_event",
      "subject": "<Subject>",
      "body_sha256": "<Body Sha256>",
      "signature_header": "<Signature Header>",
      "attempt": 1,
      "state": "pending",
      "created_at": "2026-09-13T12:00:00Z",
      "response_status": 1,
      "response_body_head": "string",
      "next_attempt_at": "2026-09-13T12:00:00Z",
      "dead_lettered_at": "2026-09-13T12:00:00Z"
    }
  ],
  "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"
      ]
    }
  ]
}
POST/webhook/{webhook}/deliveryAPI key

Send a signed test delivery

Delivers one synthetic event now and returns the live result, signature and response included.

Operation ID post_delivery_webhook__webhook__delivery_post

Parameters

path

webhookrequiredstring
A whk_ id.

Responses

200
Single_Delivery_
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 POST 'http://localhost:8000/webhook/webhook_123/delivery' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "event_type": "change_event",
  "synthetic": true
}'

Request body

DeliveryTest

{
  "event_type": "change_event",
  "synthetic": true
}

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": {
    "seq": 1,
    "event_type": "change_event",
    "subject": "<Subject>",
    "body_sha256": "<Body Sha256>",
    "signature_header": "<Signature Header>",
    "attempt": 1,
    "state": "pending",
    "created_at": "2026-09-13T12:00:00Z",
    "response_status": 1,
    "response_body_head": "string",
    "next_attempt_at": "2026-09-13T12:00:00Z",
    "dead_lettered_at": "2026-09-13T12:00:00Z"
  },
  "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>"
  }
}

coverage

1 operation

What we hold per jurisdiction per layer, including what we do not.

GET/coverageAPI key

What we cover, per jurisdiction per layer, including what we do not

Sortable: jurisdiction.name (default), tier, fill_pct, checked_at, population, data_horizon.

Operation ID list_coverage_coverage_get

Parameters

query

layer"authority" | "district" | "district_map" | "overlay"[]
No description.
tier"missing" | "partial" | "reliable"[]
No description.
outcome"present" | "absent_confirmed" | "not_published" | "unreachable"[]
No description.
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.
includestring | null
Comma-separated: field, source.
sortstring | null
field or -field, comma-separated, at most three. Sortable fields are listed per operation.
cursorstring | null
From a previous page's page.next_cursor.
sizeinteger | null
Default 25.
regionstring | null
A saved rgn_ region, or a statistical area such as a CBSA (sta_ id). Membership resolves at as_of.
jurisdictionstring[]
A jur_ id or fips_key. Repeatable.
statestring | null
Two-letter postal code or two-digit FIPS.
countystring | null
County FIPS, 5 digits, or a county's jur_ id.
geometrystring | null
WKT or GeoJSON. Jurisdictions that intersect it.
buffernumber | null
Feet around geometry.

Responses

200
CoverageAnswer
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/coverage?layer=zoning&as_of=2026-09-13&size=50' \
  -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": [
    {
      "jurisdiction": "<JurisdictionRef>",
      "layer": "authority",
      "outcome": "present",
      "tier": "missing",
      "denominator_note": "<Denominator Note>",
      "checked_at": "2026-09-13T12:00:00Z",
      "fill_pct": 1.25,
      "covered_from": "2026-09-13",
      "covered_through": "2026-09-13",
      "effective_as_of": "2026-09-13",
      "data_horizon": "2026-09-13"
    }
  ],
  "page": {
    "size": 1,
    "next_cursor": "string",
    "indeterminate": 0,
    "total": "<envelope__Total>"
  },
  "rollup": {
    "jurisdiction_count": 1,
    "covered_count": 1,
    "population_total": 1,
    "population_covered": 1,
    "by_tier": {
      "key": 1
    }
  },
  "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>"
  }
}

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

Next

Bulk, maps and research

19 operations: extract, map, ogc, inquiry.