openapi: 3.1.0
info:
  title: Shovels Addresses Geography API
  description: The Shovels API provides building permit intelligence and contractor data aggregated from 1,800+ jurisdictions across the United States. Access 130M+ building permits, 2.3M+ contractor profiles, property details, resident information, and geographic metrics. The API is used by materials suppliers, construction tech companies, energy and climate firms, home services companies, real estate professionals, and telecommunications providers to power sales, marketing, and market analytics.
  version: v2
  contact:
    name: Shovels Support
    url: https://docs.shovels.ai
    email: sales@shovels.ai
  termsOfService: https://www.shovels.ai/terms
servers:
- url: https://api.shovels.ai/v2
  description: Shovels API v2
security:
- ApiKeyAuth: []
tags:
- name: Geography
paths:
  /cities/search:
    get:
      operationId: searchCities
      summary: Search Cities
      description: Searches for cities by name to retrieve geo_id values for use in other API calls.
      tags:
      - Geography
      parameters:
      - name: q
        in: query
        required: true
        description: City name search term
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of matching cities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoListResponse'
  /cities/{geo_id}:
    get:
      operationId: getCityById
      summary: Get City By ID
      description: Returns city details and location hierarchy.
      tags:
      - Geography
      parameters:
      - name: geo_id
        in: path
        required: true
        description: City geo_id
        schema:
          type: string
      responses:
        '200':
          description: City details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoLocation'
  /cities/{geo_id}/metrics/current:
    get:
      operationId: getCityMetricsCurrent
      summary: Get City Metrics Current
      description: Returns current permit activity metrics for a city.
      tags:
      - Geography
      parameters:
      - name: geo_id
        in: path
        required: true
        description: City geo_id
        schema:
          type: string
      responses:
        '200':
          description: Current city metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoMetrics'
  /counties/search:
    get:
      operationId: searchCounties
      summary: Search Counties
      description: Searches for counties by name.
      tags:
      - Geography
      parameters:
      - name: q
        in: query
        required: true
        description: County name search term
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of matching counties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoListResponse'
  /jurisdictions/search:
    get:
      operationId: searchJurisdictions
      summary: Search Jurisdictions
      description: Searches for building permit jurisdictions by name.
      tags:
      - Geography
      parameters:
      - name: q
        in: query
        required: true
        description: Jurisdiction name search term
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of matching jurisdictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoListResponse'
  /states/search:
    get:
      operationId: searchStates
      summary: Search States
      description: Searches for US states based on the provided search term.
      tags:
      - Geography
      parameters:
      - name: q
        in: query
        required: true
        description: State name search term
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page (1-100, default 50)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: List of matching states
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoListResponse'
  /zipcodes/search:
    get:
      operationId: searchZipcodes
      summary: Search Zipcodes
      description: Searches for US zip codes.
      tags:
      - Geography
      parameters:
      - name: q
        in: query
        required: true
        description: Zip code search term
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of matching zip codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoListResponse'
components:
  schemas:
    GeoMetrics:
      type: object
      properties:
        geo_id:
          type: string
        permit_count:
          type: integer
        active_permits:
          type: integer
        avg_job_value:
          type: number
        contractor_count:
          type: integer
        period:
          type: string
          format: date
    GeoLocation:
      type: object
      properties:
        geo_id:
          type: string
        name:
          type: string
        state:
          type: string
        county:
          type: string
        latitude:
          type: number
        longitude:
          type: number
    TotalCount:
      type: object
      properties:
        value:
          type: integer
          description: Total count value (capped at 10,000)
        relation:
          type: string
          enum:
          - eq
          - gte
          description: Whether the value is exact (eq) or a lower bound (gte)
    GeoListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GeoLocation'
        size:
          type: integer
        next_cursor:
          type: string
          nullable: true
        total_count:
          $ref: '#/components/schemas/TotalCount'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from app.shovels.ai Profile Settings