query

Combinable closed-catalog query. Scope required. Row-capped. Cursor-paginated.

Provide a closed q, named slots, or a structured catalog filter; supplied controls combine with AND and are validated through the builder whitelist. A field not held by the scoped county returns an honest empty. Exactly one of scope.fips, scope.state, or scope.held is required; scope.held=[all] searches loaded non-Vermont counties. Omit-select rows include the 91 canonical_fields in schema order; unheld values are null. A named select keeps the requested keys and is not forced to 91. Metering: charges search (1) on accept and record_reveal per returned row. scope_coverage describes requested geography versus schema-bindable counties, independently of positive/zero rows and pagination. State scope uses the pinned current Census spine plus loaded historical counties, explicitly marked legacy. Wholly unloaded scope returns 400 county-not-held, not field-not-held or no matches.

post/v1/query

Request

  • Base URL: https://api.premiumpin.com
  • URL: https://api.premiumpin.com/v1/query
  • Auth: one of:
    • HTTP bearer
    • API key in cookie pp_session

Headers

Idempotency-Keystring

Dedupes metered charges on retried requests (see billing meter idempotency).

Request body

cursorstring

opaque keyset cursor from a prior response. Bound to store_version + query; else 400/410.

limitinteger
qstring

Closed English question over held catalog slots. Not freehand SQL.

selectstring[]

Return-field whitelist from the public field catalog. Private internal fields are never allowed.

slotsobject

Named closed-catalog slots. Combined with filter.filters using AND. tax_amount and subdivision_name are rejected.

Response

matching parcels (projected, PII-gated by entitlement, suppression-filtered)

bindable_fipsstring[]
countinteger

rows returned (<= limit)

empty_reason'field-not-held' nullable
honest_emptyboolean
miss_reasonstring nullable
next_cursorstring nullable

pass as cursor for the next page; null on last page

question_idstring nullable
store_versionstring
truncatedboolean

more rows exist beyond this page

unavailable_fieldsstring[]

Named fields not held by the scoped county; present on field-not-held honest empties.

Changes

No recorded changes to this operation across all 1 revision of this API.