DrillerDB Well data API

openapi: 3.2.0
info:
  title: DrillerDB Public Well data API
  version: '2026-10-07'
  summary: Well data, driller directory, and DrillerDB application APIs
  description: 'Machine-readable description of every public DrillerDB endpoint, in three groups, each with its own server:


    1. drillerdb.com: free, unauthenticated JSON endpoints (well depth and water-table lookup, driller directory and license search, ZIP geocoding, platform stats, conference calendars). Errors are {error, message}. An /api path with no endpoint answers 404, and a method an endpoint does not support answers 405 with an Allow header; both bodies add hint and documentation (ApiRoutingError).

    2. app.drillerdb.com/api/v1: read-only access to a DrillerDB customer''s own projects, invoices, work orders, contacts, equipment and inventory. Requires an X-API-Key issued to an Enterprise-plan company; each key carries scopes and each operation names the scope it needs in x-required-scope. Errors are {error:{code,message,hint}, meta:{request_id}, links}.

    3. enterprise.drillerdb.com/api/mcp: Model Context Protocol server for DrillerDB Enterprise (prospect intelligence), OAuth 2.1 with the mcp:read:enterprise scope.


    Rate limits on drillerdb.com: 500 requests per IP address per 60 seconds, counted across page views and API requests together, not per endpoint. Every /api response the limiter counted carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers-11); a 429 also carries Retry-After in seconds.


    Versioning and deprecation: the keyed APIs carry their major version in the path (app.drillerdb.com/api/v1, console.drillerdb.com/api/partner/v1). Additive changes, such as new fields, new optional parameters and new operations, stay in the current version; a breaking change ships under a new major version path. A deprecated version says so on every response with the Deprecation header (RFC 9745), the Sunset header (RFC 8594) and a Link header with rel="deprecation". At least 12 months pass between the date a version first sends the Deprecation header and its Sunset date. No version is deprecated today. Details: https://drillerdb.com/docs/integrations/api-conventions.


    Any HTML page on drillerdb.com can be fetched as Markdown with Accept: text/markdown. Site index for agents: https://drillerdb.com/llms.txt.'
  termsOfService: https://drillerdb.com/terms
  contact:
    name: DrillerDB
    url: https://drillerdb.com/contact-us
    email: support@drillerdb.com
servers:
- url: https://drillerdb.com
  description: drillerdb.com public endpoints (no key)
tags:
- name: Well data
  description: Depth and water-table statistics from the public well dataset
paths:
  /api/well-depth-lookup:
    get:
      tags:
      - Well data
      operationId: getWellDepthLookup
      summary: Well depth and water-table statistics around a coordinate
      description: Returns well-depth and static-water-level (water table) statistics computed from recorded wells near a US coordinate, plus a sample of the nearest wells. Public, no key. Rate limited per IP; responses are cached for up to six hours. Locations outside the United States are rejected.
      parameters:
      - name: lat
        in: query
        required: true
        description: 'Latitude in decimal degrees (WGS84). US only: 18 to 72.'
        schema:
          type: number
          minimum: 18
          maximum: 72
        example: 44.5236
      - name: lng
        in: query
        required: true
        description: 'Longitude in decimal degrees (WGS84). US only: -178 to -66.'
        schema:
          type: number
          minimum: -178
          maximum: -66
        example: -89.5746
      responses:
        '200':
          description: Statistics for the area; an insufficient_data body (still 200) when too few wells are recorded nearby to estimate; or a too_many_wells body (still 200) when the area has so many recorded wells that the statistics could not be computed in time.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/WellDepthResult'
                - $ref: '#/components/schemas/WellDepthInsufficientData'
                - $ref: '#/components/schemas/WellDepthTooManyWells'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '400':
          description: lat/lng missing or not numbers, or outside the United States.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SiteError'
                - properties:
                    error:
                      type: string
                      enum:
                      - invalid_params
                      - out_of_bounds
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '429':
          description: Too many requests from this IP address. Wait the number of seconds in Retry-After.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SiteError'
                - properties:
                    error:
                      type: string
                      enum:
                      - rate_limited
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '500':
          description: The lookup failed; retry.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SiteError'
                - properties:
                    error:
                      type: string
                      enum:
                      - lookup_failed
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
components:
  schemas:
    NearbyWell:
      type: object
      properties:
        distance_mi:
          type:
          - number
          - 'null'
        depth_ft:
          type:
          - number
          - 'null'
        swl_ft:
          type:
          - number
          - 'null'
          description: Static water level below ground, feet.
        yield_gpm:
          type:
          - number
          - 'null'
        year:
          type:
          - integer
          - 'null'
        county:
          type:
          - string
          - 'null'
      required:
      - distance_mi
      - depth_ft
      - swl_ft
      - yield_gpm
      - year
      - county
    WellDepthInsufficientData:
      type: object
      description: Returned with status 200 when too few wells are recorded near the point.
      properties:
        well_count:
          type: integer
          enum:
          - 0
        error:
          type: string
          enum:
          - insufficient_data
        reason:
          type: string
          enum:
          - oil_gas_only
          - non_water_supply_only
          description: 'Present when well records exist near the point but none is a water-supply well, so no water-well estimate is possible: oil_gas_only when every record is an oil or gas well, non_water_supply_only when every record is an oil or gas, monitoring, test or other non-water-supply well.'
        message:
          type: string
      required:
      - well_count
      - error
      - message
    WellDepthResult:
      type: object
      properties:
        well_count:
          type: integer
          description: Recorded wells inside the radius.
        swl_count:
          type: integer
          description: Of those, wells with a static water level.
        radius_km:
          type: number
        radius_mi:
          type: number
        expanded_radius:
          type: boolean
          description: True when the search widened to find enough wells.
        depth_unit:
          type: string
          enum:
          - ft
        depth_min:
          type:
          - number
          - 'null'
        depth_max:
          type:
          - number
          - 'null'
        depth_p25:
          type:
          - number
          - 'null'
        depth_p50:
          type:
          - number
          - 'null'
          description: Median well depth, feet.
        depth_p75:
          type:
          - number
          - 'null'
        has_swl:
          type: boolean
        swl_p25:
          type:
          - number
          - 'null'
        swl_p50:
          type:
          - number
          - 'null'
          description: Median static water level (water table), feet below ground.
        swl_p75:
          type:
          - number
          - 'null'
        top_aquifer:
          type:
          - string
          - 'null'
        nearby:
          type: array
          items:
            $ref: '#/components/schemas/NearbyWell'
        cached_at:
          type: string
          format: date-time
      required:
      - well_count
      - swl_count
      - radius_km
      - radius_mi
      - expanded_radius
      - depth_unit
      - depth_min
      - depth_max
      - depth_p25
      - depth_p50
      - depth_p75
      - has_swl
      - swl_p25
      - swl_p50
      - swl_p75
      - top_aquifer
      - nearby
      - cached_at
    WellDepthTooManyWells:
      type: object
      description: Returned with status 200 when the area has so many recorded wells that the statistics query ran past its time limit. No statistics are returned.
      properties:
        error:
          type: string
          enum:
          - too_many_wells
        message:
          type: string
      required:
      - error
      - message
    SiteError:
      type: object
      description: Error body returned by every drillerdb.com JSON endpoint.
      properties:
        error:
          type: string
          description: Machine-readable code.
        message:
          type: string
          description: What went wrong and what to do.
      required:
      - error
      - message
  headers:
    RetryAfter:
      description: Seconds to wait before the next request (RFC 9110, section 10.2.3).
      schema:
        type: integer
        minimum: 1
      example: 45
    RateLimit:
      description: 'Current service limit (draft-ietf-httpapi-ratelimit-headers-11, section 4): r = requests left, t = seconds until the oldest counted request leaves the 60-second window. Absent when the limiter did not count the request.'
      schema:
        type: string
      example: '"default";r=499;t=60'
    RateLimitPolicy:
      description: 'Quota policy (draft-ietf-httpapi-ratelimit-headers-11, section 3): 500 requests per 60 seconds per IP address, counted across page views and API requests together, not per endpoint. Sent whenever the limiter counted the request.'
      schema:
        type: string
      example: '"default";q=500;w=60'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Company API key issued in DrillerDB Settings > API Access (Enterprise plan). Keys are scoped; the scopes a key may hold are projects:read, invoices:read, work_orders:read, contacts:read, equipment:read and inventory:read. A key lacking the scope an operation needs receives 403 INSUFFICIENT_SCOPE with meta.required_scope.
    EnterpriseMcpOAuth:
      type: oauth2
      description: 'OAuth 2.1 authorization-code flow with PKCE (S256), as published at https://enterprise.drillerdb.com/.well-known/oauth-authorization-server. Dynamic client registration is available at https://enterprise.drillerdb.com/oauth/register. Tokens are presented as Bearer in the Authorization header. Protected-resource metadata (RFC 9728): https://enterprise.drillerdb.com/.well-known/oauth-protected-resource.'
      flows:
        authorizationCode:
          authorizationUrl: https://enterprise.drillerdb.com/oauth/authorize
          tokenUrl: https://enterprise.drillerdb.com/oauth/token
          refreshUrl: https://enterprise.drillerdb.com/oauth/token
          scopes:
            mcp:read:enterprise: Read drilling-company prospect data, lead scores, lists, territories, and market signals on the user's behalf (read-only).
externalDocs:
  description: When to use DrillerDB and how an agent calls us (llms.txt)
  url: https://drillerdb.com/llms.txt
x-generated-by: scripts/build-openapi.mjs
x-legacy-spec-source: https://app.drillerdb.com/api/v1/openapi.json