openapi: 3.0.3
info:
  title: Regrid Parcel Metadata API
  description: 'RESTful API for querying US and Canadian parcel records by location (lat/lon), street address, assessor parcel number (APN), owner name, or polygon area. Returns GeoJSON FeatureCollections with parcel boundaries, ownership, zoning, assessed values, and deed attributes. Supports up to 1,000 records per request with usage tracked by parcel records returned for billing purposes.

    '
  version: 2.0.0
  termsOfService: https://regrid.com/terms
  contact:
    name: Regrid Support
    url: https://support.regrid.com
  license:
    name: Proprietary
    url: https://regrid.com/terms
servers:
- url: https://app.regrid.com
  description: Regrid Production API
security:
- apiToken: []
tags:
- name: Metadata
  description: Coverage, usage, and data quality endpoints
paths:
  /verse:
    get:
      operationId: getVerse
      summary: County Coverage Metadata
      description: 'Returns county-level metadata including coverage status, field availability, and data refresh dates for all covered US counties and Canadian provinces.

        '
      tags:
      - Metadata
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Array of county coverage records
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CountyCoverage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage:
    get:
      operationId: getUsage
      summary: API Usage Summary
      description: Returns current API usage summary against plan limits
      tags:
      - Metadata
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Usage summary object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage/detailed:
    get:
      operationId: getDetailedUsage
      summary: Detailed API Usage
      description: Returns granular usage breakdown by endpoint and date
      tags:
      - Metadata
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
      - name: start_date
        in: query
        required: false
        description: Start date for usage range (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        required: false
        description: End date for usage range (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Detailed usage breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /report:
    post:
      operationId: submitDataReport
      summary: Submit Data Quality Report
      description: Submit a data quality report for a specific parcel
      tags:
      - Metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ll_uuid
              - issue
              properties:
                ll_uuid:
                  type: string
                  format: uuid
                  description: Regrid UUID of the parcel being reported
                issue:
                  type: string
                  description: Description of the data quality issue
                fields:
                  type: array
                  items:
                    type: string
                  description: Specific fields affected by the issue
      responses:
        '200':
          description: Report submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  report_id:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DetailedUsage:
      type: object
      description: Granular usage breakdown by endpoint and date
      properties:
        usage:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              endpoint:
                type: string
              records:
                type: integer
              requests:
                type: integer
    CountyCoverage:
      type: object
      description: County-level coverage metadata record
      properties:
        name:
          type: string
          description: County name
        state_abbr:
          type: string
          description: State abbreviation
        fips:
          type: string
          description: FIPS county code
        parcel_count:
          type: integer
          description: Number of parcel records for this county
        last_refresh:
          type: string
          format: date
          description: Date of last data refresh
        fields_available:
          type: array
          items:
            type: string
          description: List of schema fields available for this county
    UsageSummary:
      type: object
      description: API usage summary against plan limits
      properties:
        plan:
          type: string
          description: Current subscription plan name
        period_start:
          type: string
          format: date
          description: Current billing period start date
        period_end:
          type: string
          format: date
          description: Current billing period end date
        records_used:
          type: integer
          description: Parcel records returned in the current period
        records_limit:
          type: integer
          description: Plan record limit for the current period
        records_remaining:
          type: integer
          description: Records remaining in the current period
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API token
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    BadRequest:
      description: Bad request — invalid parameters or missing required fields
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: token
      description: API token obtained from your Regrid account profile
externalDocs:
  description: Regrid API Documentation
  url: https://support.regrid.com/api/section/parcel-api