Boardwalk Locations API

openapi: 3.2.0
info:
  title: Boardwalkai Com Locations API
  version: '2026-09-16'
  contact:
    name: Boardwalk Support
    email: support@boardwalkai.com
    url: https://boardwalkai.com
  description: 'Operations tagged Locations across 2 of this provider''s published API definitions: boardwalkai-com-openapi.json, boardwalkai-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.boardwalkai.com/api/v1
  description: Production
- url: http://localhost:8000/api/v1
  description: Local development
security:
- bearerAuth: []
tags:
- name: Locations
  description: States, counties, and cities. IDs from here are used as filter values in project search.
paths:
  /locations/states:
    get:
      tags:
      - Locations
      summary: List all states
      description: States in the catalogue with numeric IDs, names, and approximate centroid coordinates. Coverage is per-state. On search/count/analytics you may send `states` as ids, USPS abbreviations (e.g. `UT`), or full names, which resolve to ids for lookup. Free.
      responses:
        '200':
          description: List of states.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateListResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsStates
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /locations/states/{id}:
    get:
      tags:
      - Locations
      summary: Get one state
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: State record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: State not found.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsStatesById
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /locations/states/{id}/counties:
    get:
      tags:
      - Locations
      summary: List counties in a state
      description: County IDs for the `counties` filter (aliases `county`, `countyId`, `countyIds`) on `/projects/search`. Free.
      parameters:
      - name: id
        in: path
        required: true
        description: State ID
        schema:
          type: integer
      responses:
        '200':
          description: List of counties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyListResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: State not found.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsStatesByIdCounties
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /locations/states/{stateId}/counties/{countyId}/cities:
    get:
      tags:
      - Locations
      summary: List cities in a county
      parameters:
      - name: stateId
        in: path
        required: true
        schema:
          type: integer
      - name: countyId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: List of cities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityListResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: County not found in the specified state.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsStatesByStateIdCountiesByCountyIdCities
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /locations/counties/{id}:
    get:
      tags:
      - Locations
      summary: Get one county
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: County record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyDetailResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: County not found.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsCountiesById
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /locations/cities/{id}:
    get:
      tags:
      - Locations
      summary: Get one city
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: City record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityDetailResponse'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: City not found.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLocationsCitiesById
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
components:
  schemas:
    StateResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/State'
        meta:
          $ref: '#/components/schemas/GeographyScopeMeta'
    City:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
    CountyDetail:
      allOf:
      - $ref: '#/components/schemas/County'
      - type: object
        properties:
          stateId:
            type: integer
          stateName:
            type: string
    CityDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CityDetail'
    CityDetail:
      allOf:
      - $ref: '#/components/schemas/City'
      - type: object
        properties:
          stateId:
            type: integer
          stateName:
            type: string
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - param
          - details
          - docsUrl
          - requestId
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this value.
            message:
              type: string
              description: Human-readable explanation. Do not parse it.
            param:
              type:
              - string
              - 'null'
              description: The offending input parameter, when applicable.
            details:
              type: object
              description: Structured, camelCase context. Always an object, empty when there is no context.
              additionalProperties: true
            docsUrl:
              type: string
              format: uri
              description: Documentation for this exact error code.
            requestId:
              type: string
              description: Matches X-Request-Id and the server-side usage/log record.
          additionalProperties: false
      additionalProperties: false
    CountyDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CountyDetail'
    GeographyScopeMeta:
      type: object
      description: The geographic ceiling on your plan, stated once instead of inferred from the per-state `entitled` flags.
      properties:
        geographyScope:
          type: string
          enum:
          - nationwide
          - states
          - counties
          - none
          description: The shape of your entitlement. `nationwide` reaches every state without listing any; `none` is a plan that includes no API geography.
        entitledStateIds:
          type:
          - array
          - 'null'
          items:
            type: integer
          description: '**Null means every state**, not none: it is the nationwide case. An empty array means nowhere. Treating the two alike turns a denial into unrestricted access, so branch on `geographyScope` if that distinction is easier to hold.'
        countyRestricted:
          type: boolean
          description: True on a county-grain plan, where `entitled` on a state means "part of this state". Use `/locations/states/{id}/counties` to see which.
    CountyListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/County'
    CityListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/City'
    County:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        fipsCode:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
    State:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbreviation:
          type: string
          minLength: 2
          maxLength: 2
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        entitled:
          type: boolean
          description: Whether **your key** may filter on this state. False means a query naming it returns `403 geographic_access_denied`. Always true on a nationwide plan. Every state is listed either way, so this is the field to build a picker against, not the presence of the row.
    StateListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/State'
        meta:
          $ref: '#/components/schemas/GeographyScopeMeta'
  responses:
    PaymentRequired:
      description: 'Subscription missing, credits exhausted, or the page this request would deliver costs more than the balance has left.


        * `subscription_required`: no active paid plan or trial behind this key.

        * `credits_exhausted`: the balance cannot cover even one record and this response would have billed at least one. Re-reads of unchanged records you already own bill 0 and are still served at 0 balance. Paid balances refill on the 1st; trial credits never do.

        * `insufficient_credits`: the balance has credits left, but fewer than this page would cost. A page is delivered whole or refused whole, never trimmed, so **no records are returned and nothing is charged**. `details.quote` states the page''s cost, what remains, `affordableRecordCount` (the `limit` to retry with), and a free `countUrl` that re-prices the whole match set. Free-trial pages are truncated instead of refused here; see `meta.trialTruncation`.

        * `enrichment_requires_paid_plan`: `include=contacts` (Find Contact Info) needs a paid plan or a live trial. Record credits may still remain. Drop the parameter, start a trial, or upgrade.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: credits_exhausted
              message: You have used all your API credits for this billing period. Credits reset on the 1st of each month.
              param: null
              details:
                creditsUsed: 5000
                creditsLimit: 5000
                resetsAt: '2026-06-01T00:00:00Z'
              docsUrl: https://boardwalkai.com/docs/api/errors#credits_exhausted
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: missing_api_key
              message: 'API key is required. Include it as Authorization: Bearer bwk_live_... or X-API-Key: bwk_live_...'
              param: null
              details: {}
              docsUrl: https://boardwalkai.com/docs/api/errors#missing_api_key
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    RateLimitExceeded:
      description: 'Too many requests in the trailing 60 seconds. Limits are per API key: 60 requests per minute on any paid plan, 10 per minute on a free-trial key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also carries Retry-After. Before authentication, a missing credential uses a 10-per-minute source-IP bucket and an unknown or unusable Boardwalk-shaped key uses its own 10-per-minute credential-digest bucket.'
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute for the applicable key or pre-authentication bucket.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp at which the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit of 60 requests per minute exceeded. Retry in 12 seconds.
              param: null
              details:
                retryAfterSeconds: 12
              docsUrl: https://boardwalkai.com/docs/api/errors#rate_limit_exceeded
              requestId: req_01K1QF3M0000EXAMPLE0001
  headers:
    BoardwalkSchemaVersion:
      description: The date-stamped response contract version. Present on every public v1 response.
      schema:
        type: string
        example: '2026-09-16'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Boardwalk API key. Keys you create under Settings → API are prefixed `bwk_live_` and read the production corpus against your plan or free-trial balance. `bwk_test_` is reserved for a separate sandbox environment that is not serving data yet. Pre-rename `csk_` keys are accepted indefinitely. Create and rotate keys at https://boardwalkai.com/profile/api.
x-refined-from:
- boardwalkai-com-openapi.json
- boardwalkai-com-openapi.yml