Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Placestack Usage API
summary: The Placestack API.
description: 'The Placestack API: US parcels, zoning and jurisdictions.
## Paths
Paths are singular nouns, such as `/v1/parcel` and `/v1/parcel/{parcel_id}`.
## Pagination
Lists return a page at a time. Send a page''s `next_cursor` as `cursor` to get the next one, and `size`
to set the page size. Where an endpoint takes `sort`, `sort=field` sorts ascending and `sort=-field`
descending.
## Errors
Errors are RFC 9457 problem details (`application/problem+json`) with `type`, `title`, `status`,
`detail`, `code` and `field`. Handle errors by `code`.
## Updates
Updates accept an `If-Match` header with the `ETag` from your last read. A stale `ETag` is refused
with `409 version_conflict`.
## Credits
A lookup costs one credit: a parcel by address, number, point or id, or the zoning at a place. A search
costs 1 credit per 20 results, and one zoning classification, permit or case costs one credit. The
same lookup is free again for 24 hours. Requests that return nothing are free, as are jurisdictions,
suggestions and account endpoints. `GET /v1/me` returns the credit balance.
## GeoJSON
`/v1/parcel`, `/v1/zoning` and `/v1/jurisdiction` return GeoJSON with `format=geojson` or
`Accept: application/geo+json`: a `FeatureCollection` for a list, a `Feature` for one object. The
boundary is the geometry and the object is the properties. `include=geometry` adds the boundary to
the JSON response instead.
## Webhooks
Deliveries are signed with Standard Webhooks headers (`webhook-id`, `webhook-timestamp`,
`webhook-signature`), so any Standard Webhooks library can verify them. An event can be delivered
more than once: deduplicate on `webhook-id`. `GET /event_type` lists the event types.
A `permit.created` or `case.created` event''s `data` holds the record''s `id` and `href`, and the
`monitor` and `list_item` ids it matched. Retrieve the record at `href`, which costs a credit.'
version: 0.0.0
servers:
- url: http://localhost:3030
description: Development.
tags:
- name: Usage
description: Requests, credits spent and the credit balance.
paths:
/usage:
get:
tags:
- Usage
summary: Retrieve usage
description: Returns requests and credits used in the period, in total and by day, endpoint and API key.
operationId: read_usage
security:
- HTTPBearer: []
parameters:
- name: days
in: query
required: false
schema:
type: integer
maximum: 365
minimum: 1
description: Number of days to include, ending now, between 1 and 365. Defaults to 30.
default: 30
title: Days
description: Number of days to include, ending now, between 1 and 365. Defaults to 30.
responses:
'200':
description: The usage summary.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageSummary'
'422':
description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
'401':
description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
x-credits: Free.
/credit:
get:
tags:
- Usage
summary: Retrieve credit balance
description: 'Returns the credit balance, the grants that make it up, and recent credits added or expired,
newest first.
Each entry includes `balance_after`, the balance once it applied.'
operationId: read_credit
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
description: Number of ledger entries to return, between 1 and 500. Defaults to 50.
default: 50
title: Limit
description: Number of ledger entries to return, between 1 and 500. Defaults to 50.
responses:
'200':
description: The credit balance.
content:
application/json:
schema:
$ref: '#/components/schemas/CreditView'
'422':
description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
'401':
description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
x-credits: Free.
/usage/request:
get:
tags:
- Usage
summary: List requests
description: 'Lists requests to `/v1` endpoints, newest first, with each one''s status, credits and credential.
`GET /v1/me` is not included, nor are requests refused for a missing or invalid credential.'
operationId: list_request
security:
- HTTPBearer: []
parameters:
- name: request_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only the request with this id, from the `request-id` response header.
title: Request Id
description: Only the request with this id, from the `request-id` response header.
- name: route
in: query
required: false
schema:
type: array
items:
type: string
description: Only requests to these endpoints, as path templates such as `/v1/parcel`. Repeat for several.
default: []
title: Route
description: Only requests to these endpoints, as path templates such as `/v1/parcel`. Repeat for several.
- name: key
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only requests made with this API key id.
title: Key
description: Only requests made with this API key id.
- name: user
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only requests made by this user id, directly or through an OAuth client.
title: User
description: Only requests made by this user id, directly or through an OAuth client.
- name: client
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only requests made through this OAuth client id.
title: Client
description: Only requests made through this OAuth client id.
- name: actor_method
in: query
required: false
schema:
type: array
items:
enum:
- session
- api_key
- oauth
- mcp
type: string
description: Only requests authenticated this way. One of `session`, `api_key`, `oauth` or `mcp`. Repeat for several.
default: []
title: Actor Method
description: Only requests authenticated this way. One of `session`, `api_key`, `oauth` or `mcp`. Repeat for several.
- name: error
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: '`true` for only failed requests (status `400` or above), `false` for only successful ones.'
title: Error
description: '`true` for only failed requests (status `400` or above), `false` for only successful ones.'
- name: min_occurred
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only requests received at or after this time, in ISO 8601.
title: Min Occurred
description: Only requests received at or after this time, in ISO 8601.
- name: max_occurred
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only requests received before this time, in ISO 8601.
title: Max Occurred
description: Only requests received before this time, in ISO 8601.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'A cursor for pagination: the `next_cursor` from the previous page.'
title: Cursor
description: 'A cursor for pagination: the `next_cursor` from the previous page.'
- name: size
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 200
minimum: 1
- type: 'null'
description: Number of results per page, between 1 and 200. Defaults to 20.
title: Size
description: Number of results per page, between 1 and 200. Defaults to 20.
responses:
'200':
description: A page of requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection_Request_'
'403':
description: '`api_key_not_accepted`. The request used an API key. This endpoint accepts a console session or an MCP token.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
'422':
description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
'401':
description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
x-credits: Free.
components:
schemas:
CreditView:
properties:
object:
type: string
const: credit_balance
title: Object
description: The object's type. Always `credit_balance`.
default: credit_balance
organization_id:
type: string
title: Organization Id
description: The organization's id.
examples:
- 0192f3a4-5b6c-7d8e-9f01-23456789abcd
balance:
type: integer
title: Balance
description: The current credit balance.
included_credits:
type: integer
title: Included Credits
description: Credits included with the plan each billing period. `0` without a plan.
grants:
items:
$ref: '#/components/schemas/CreditGrant'
type: array
title: Grants
description: Grants with credits left to spend, in the order they are spent.
ledger:
items:
$ref: '#/components/schemas/LedgerEntry'
type: array
title: Ledger
description: The most recent credits granted, purchased, expired or adjusted, newest first, up to `limit`. Credits spent on requests are in `/usage`.
type: object
required:
- object
- organization_id
- balance
- included_credits
- grants
- ledger
title: CreditView
Request:
properties:
object:
type: string
const: request
title: Object
description: The object's type. Always `request`.
default: request
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: The request's id, also sent as the `request-id` response header. Include it when contacting support about a request.
examples:
- req_7872540bd07601eae287aa02
occurred_at:
type: string
format: date-time
title: Occurred At
description: Time at which the request was received.
method:
type: string
title: Method
description: The HTTP method, such as `GET`.
examples:
- GET
route:
type: string
title: Route
description: The endpoint, as its path template, such as `/v1/parcel/{parcel_id}`. Path values and query strings are not stored.
examples:
- /v1/parcel
status:
type: integer
title: Status
description: The response's HTTP status.
credits:
type: integer
title: Credits
description: Credits charged.
free_reason:
anyOf:
- type: string
enum:
- cached
- not_found
- not_covered
- empty
- error
- included
- seat
- type: 'null'
title: Free Reason
description: Why no credits were charged. One of `cached` (a repeat within a day), `not_found`, `not_covered`, `empty`, `error`, `included` (a read that is never charged) or `seat` (a read in Explorer). Null when credits were charged.
duration_ms:
anyOf:
- type: integer
- type: 'null'
title: Duration Ms
description: Time to respond, in milliseconds. Null when not recorded.
actor:
$ref: '#/components/schemas/RequestActor'
description: The credential that made the request.
type: object
required:
- object
- request_id
- occurred_at
- method
- route
- status
- credits
- free_reason
- duration_ms
- actor
title: Request
description: One request to a `/v1` endpoint.
RequestActor:
properties:
kind:
type: string
enum:
- user
- machine
title: Kind
description: Whether a person or a machine credential made the request. One of `user` or `machine`.
method:
type: string
enum:
- session
- api_key
- oauth
- mcp
title: Method
description: How the request was authenticated. One of `session`, `api_key`, `oauth` or `mcp`.
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The API key's name, the user's email address or the OAuth client's name, for display. Null when there is none.
examples:
- Production
key:
anyOf:
- type: string
- type: 'null'
title: Key
description: The API key's id. Null when no API key was used.
examples:
- 0192f3a4-7d8e-7f90-b123-456789abcdef
user:
anyOf:
- type: string
- type: 'null'
title: User
description: The user's id. Null for a machine credential.
examples:
- 0192f3a4-6c7d-7e8f-a012-3456789abcde
client:
anyOf:
- type: string
- type: 'null'
title: Client
description: The OAuth client's id. Null when no OAuth client was used.
examples:
- placestack-console
type: object
required:
- kind
- method
- name
- key
- user
- client
title: RequestActor
description: The credential that made a request.
CreditGrant:
properties:
object:
type: string
const: credit_grant
title: Object
description: The object's type. Always `credit_grant`.
default: credit_grant
id:
type: string
title: Id
description: Unique identifier for the object.
examples:
- cgr_01j9z3k4m5n6p7q8r9s0t1v2w3
amount:
type: integer
title: Amount
description: Credits granted.
remaining:
type: integer
title: Remaining
description: Credits of the grant not yet spent.
category:
type: string
enum:
- paid
- promotional
title: Category
description: One of `paid` (a plan's period or a purchase) or `promotional` (signup or an adjustment).
source:
type: string
enum:
- signup
- subscription
- purchase
- adjustment
title: Source
description: One of `signup`, `subscription` (a plan's period), `purchase` or `adjustment`.
priority:
type: integer
title: Priority
description: Order of spending. Lower is spent first.
effective_at:
type: string
format: date-time
title: Effective At
description: Time from which the credits can be spent.
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: Time at which what is left lapses. Null if it does not.
created_at:
type: string
format: date-time
title: Created At
description: Time at which the object was created.
type: object
required:
- object
- id
- amount
- remaining
- category
- source
- priority
- effective_at
- expires_at
- created_at
title: CreditGrant
description: Credits granted at once, spent in order of `priority`, then soonest `expires_at`.
Total:
properties:
value:
type: integer
title: Value
description: The number of matching results.
relation:
type: string
enum:
- eq
- gte
title: Relation
description: One of `eq` (exact) or `gte` (at least `value`). Counts above 10,000 are `gte`.
type: object
required:
- value
- relation
title: Total
description: The number of matching results.
Collection_Request_:
properties:
object:
type: string
const: list
title: Object
description: The object's type. Always `list`.
default: list
data:
items:
$ref: '#/components/schemas/Request'
type: array
title: Data
description: The results on this page.
has_more:
type: boolean
title: Has More
description: Whether there are more results after this page.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: The cursor for the next page. Send it as `cursor`. Null on the last page.
examples:
- eyJrIjoiMjAyNi0xMC0wMSIsInQiOjQyfQ
suppressed:
type: integer
title: Suppressed
description: The number of matching results withheld because the plan does not include them.
default: 0
total:
anyOf:
- $ref: '#/components/schemas/Total'
- type: 'null'
description: The number of matching results. Only on the first page, when `total=true` is sent. Null otherwise.
type: object
required:
- object
- data
- has_more
- next_cursor
- suppressed
- total
title: Collection[Request]
ProblemFieldError:
properties:
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: The invalid parameter.
detail:
type: string
title: Detail
description: What is wrong with it.
type: object
required:
- detail
title: ProblemFieldError
LedgerEntry:
properties:
delta:
type: integer
title: Delta
description: Credits added, as a positive number, or spent, as a negative one.
grant:
anyOf:
- type: string
- type: 'null'
title: Grant
description: The credit grant the credits were added to or taken from.
examples:
- cgr_01j9z3k4m5n6p7q8r9s0t1v2w3
reason:
type: string
title: Reason
description: One of `signup`, `subscription`, `purchase`, `expiry` or `adjustment`.
examples:
- purchase
reference:
anyOf:
- type: string
- type: 'null'
title: Reference
description: The billing event's id for `purchase`, `subscription` and `expiry`. Null otherwise.
examples:
- evt_1Q2w3E4r5T6y7U8i
balance_after:
type: integer
title: Balance After
description: The credit balance after this entry.
created_at:
type: string
format: date-time
title: Created At
description: Time at which the object was created.
type: object
required:
- delta
- reason
- balance_after
- created_at
title: LedgerEntry
ProblemDetail:
properties:
type:
type: string
title: Type
description: 'A link to the error code''s documentation: `https://placestack.com/docs/api/error#<code>`.'
title:
type: string
title: Title
description: A short, fixed name for the error code.
status:
type: integer
title: Status
description: The HTTP status.
detail:
type: string
title: Detail
description: A message about this occurrence, and how to resolve it.
code:
type: string
title: Code
description: The error code. Handle errors by this value.
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: The parameter that caused the error. Null when none did.
errors:
anyOf:
- items:
$ref: '#/components/schemas/ProblemFieldError'
type: array
- type: 'null'
title: Errors
description: Every invalid parameter. Only with `parameter_invalid`.
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: The request's id, also sent as the `request-id` response header. Include it when contacting support about a request.
type: object
required:
- type
- title
- status
- detail
- code
title: ProblemDetail
description: An error, as RFC 9457 problem details (`application/problem+json`).
usage__Point:
properties:
day:
type: string
format: date-time
title: Day
description: The day, at midnight UTC.
requests:
type: integer
title: Requests
description: Requests made that day.
credits:
type: integer
title: Credits
description: Credits spent that day.
type: object
required:
- day
- requests
- credits
title: Point
description: One day's totals.
Breakdown:
properties:
name:
type: string
title: Name
description: The endpoint, such as `/v1/parcel`, or the API key's name. `Console`, `MCP` or `OAuth` for requests made without an API key.
examples:
- /v1/parcel
requests:
type: integer
title: Requests
description: Requests made.
credits:
type: integer
title: Credits
description: Credits spent.
type: object
required:
- name
- requests
- credits
title: Breakdown
UsageSummary:
properties:
object:
type: string
const: usage_summary
title: Object
description: The object's type. Always `usage_summary`.
default: usage_summary
organization_id:
type: string
title: Organization Id
description: The organization's id.
examples:
- 0192f3a4-5b6c-7d8e-9f01-23456789abcd
since:
type: string
format: date-time
title: Since
description: The start of the period.
until:
type: string
format: date-time
title: Until
description: 'The end of the period: the time of the request.'
requests:
type: integer
title: Requests
description: Requests made in the period.
credits_spent:
type: integer
title: Credits Spent
description: Credits spent in the period.
free_requests:
type: integer
title: Free Requests
description: 'Successful requests that cost no credits: free endpoints, repeat requests within a day, empty results and reads in Explorer.'
credit_balance:
type: integer
title: Credit Balance
description: The current credit balance.
included_credits:
type: integer
title: Included Credits
description: Credits included with the plan each billing period. `0` without a plan.
daily:
items:
$ref: '#/components/schemas/usage__Point'
type: array
title: Daily
description: Requests and credits by day, oldest first.
by_endpoint:
items:
$ref: '#/components/schemas/Breakdown'
type: array
title: By Endpoint
description: Requests and credits by endpoint, most credits first. At most 20.
by_key:
items:
$ref: '#/components/schemas/Breakdown'
type: array
title: By Key
description: Requests and credits by API key, most credits first. At most 20. Requests made without a key are grouped as `Console`, `MCP` or `OAuth`.
type: object
required:
- object
- organization_id
- since
- until
- requests
- credits_spent
- free_requests
- credit_balance
- included_credits
- daily
- by_endpoint
- by_key
title: UsageSummary
description: Requests and credits over a period.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
x-tagGroups:
- name: Parcels
tags:
- parcel
- suggestion
- name: Zoning
tags:
- zoning
- name: Permits and cases
tags:
- permit
- case
- name: Jurisdictions
tags:
- jurisdiction
- name: Lists
tags:
- list
- name: Monitoring
tags:
- monitor
- event
- name: Webhooks
tags:
- webhook
- name: Account
tags:
- account
- usage