placestack-com Suggestion API

openapi: 3.2.0
info:
  title: Placestack Suggestion 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: suggestion
  description: 'Matches for typed text, for search-as-you-type: jurisdictions, addresses and parcel numbers.'
paths:
  /v1/suggestion:
    get:
      tags:
      - suggestion
      summary: Suggest matches for typed text
      description: 'Suggests jurisdictions, addresses and parcel numbers as the user types.


        Each match includes the `query` parameters that fetch it and, where one

        exists, its `href`.'
      operationId: list_suggestion
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 120
          description: The text typed so far. At least 2 characters.
          title: Q
        description: The text typed so far. At least 2 characters.
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - address
              - parcel
              - jurisdiction
              type: string
          - type: 'null'
          description: Kinds of match to include. One of `address`, `parcel` or `jurisdiction`. Repeatable. Defaults to all kinds.
          title: Kind
        description: Kinds of match to include. One of `address`, `parcel` or `jurisdiction`. Repeatable. Defaults to all kinds.
      - name: jurisdiction
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              pattern: ^jur_[0-7][0-9a-hjkmnp-tv-z]{25}$
              description: A jurisdiction id.
              examples:
              - jur_01h455vb4pex5vsknk084sn02q
          - type: 'null'
          description: A jurisdiction id. Address and parcel matches are limited to it. Repeatable.
          title: Jurisdiction
        description: A jurisdiction id. Address and parcel matches are limited to it. Repeatable.
      - name: fips
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: 'A Census GEOID: 2 digits for a state or 5 for a county, such as `48` or `48453`. Address and parcel matches are limited to it. Repeatable.'
          title: Fips
        description: 'A Census GEOID: 2 digits for a state or 5 for a county, such as `48` or `48453`. Address and parcel matches are limited to it. Repeatable.'
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 20
          minimum: 1
          description: Maximum number of suggestions, between 1 and 20. Defaults to 8.
          default: 8
          title: Size
        description: Maximum number of suggestions, between 1 and 20. Defaults to 8.
      responses:
        '200':
          description: A page of suggestions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection_Suggestion_'
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          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'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '501':
          description: '`not_available`. Suggestions are not available yet.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      x-credits: Free.
components:
  schemas:
    Suggestion:
      properties:
        object:
          type: string
          const: suggestion
          title: Object
          description: The object's type. Always `suggestion`.
          default: suggestion
        kind:
          type: string
          enum:
          - address
          - parcel
          - jurisdiction
          title: Kind
          description: Kind of match. One of `address`, `parcel` or `jurisdiction`.
        label:
          type: string
          title: Label
          description: 'Display text: the address, parcel number or jurisdiction name.'
          examples:
          - 4516 Printer Ln
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
          description: Secondary display text, such as the county for an address or the state for a county. Null when not needed.
          examples:
          - Raleigh, Wake County, NC
        query:
          additionalProperties:
            type: string
          type: object
          title: Query
          description: Query parameters for `GET /v1/parcel`, or `GET /v1/jurisdiction` for a jurisdiction. Send them unchanged.
        href:
          anyOf:
          - type: string
          - type: 'null'
          title: Href
          description: The matched object's path in the API. Null for an address that matches several parcels.
          examples:
          - /v1/parcel/prc_01h455vb4pex5vsknk084sn02q
      type: object
      required:
      - object
      - kind
      - label
      - detail
      - query
      - href
      title: Suggestion
      description: A suggested match for typed text.
    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.
    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
    Collection_Suggestion_:
      properties:
        object:
          type: string
          const: list
          title: Object
          description: The object's type. Always `list`.
          default: list
        data:
          items:
            $ref: '#/components/schemas/Suggestion'
          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[Suggestion]
    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`).
  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