DrillerDB Geocoding API

openapi: 3.2.0
info:
  title: DrillerDB Public Geocoding 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: Geocoding
  description: ZIP code resolution used by the directory
paths:
  /api/geo/zip:
    get:
      tags:
      - Geocoding
      operationId: geocodeZip
      summary: Resolve a US ZIP code to a coordinate
      description: Returns the centroid, city and state for a five-digit US ZIP code. Public, no key. Rate limited per IP; results are cached for a day.
      parameters:
      - name: zip
        in: query
        required: true
        description: Five-digit US ZIP code.
        schema:
          type: string
          pattern: ^\d{5}$
        example: '54401'
      responses:
        '200':
          description: Centroid of the ZIP code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZipPoint'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '400':
          description: zip is not five digits.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SiteError'
                - properties:
                    error:
                      type: string
                      enum:
                      - invalid_zip
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '404':
          description: The ZIP code is not known.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SiteError'
                - properties:
                    error:
                      type: string
                      enum:
                      - not_found
          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'
        '503':
          description: The upstream geocoder is temporarily unavailable.
          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:
    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
    ZipPoint:
      type: object
      properties:
        lat:
          type: number
        lng:
          type: number
        city:
          type: string
        state:
          type: string
          description: Two-letter state.
      required:
      - lat
      - lng
      - city
      - state
  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