openapi: 3.0.3
info:
  title: Zipwise Web Services - distance
  description: >
    Returns the Great Circle distance, in miles, between the approximate
    geographic centers of two ZIP/postal codes.
  version: "2026-04"
servers:
  - url: https://www.zipwise.com/webservices

paths:
  /distance.php:
    get:
      operationId: distance
      summary: Get distance in miles between two ZIP/postal codes
      description: >
        Accepts GET only. Counts against the account's daily call limit
        (validated via the shared account_check logic). Unlike citysearch and
        zipinfo, this method does not apply a per-session rate limit.
      parameters:
        - name: key
          in: query
          required: true
          description: Your 16-character API key.
          schema:
            type: string
            pattern: '^[a-z0-9]{16}$'
        - name: zip1
          in: query
          required: true
          description: >
            First ZIP/postal code. US ZIPs are 5 digits. Canadian postal codes
            are 6 characters entered with no space (e.g. `K1A0B1`); the space
            is inserted automatically before lookup.
          schema:
            type: string
        - name: zip2
          in: query
          required: true
          description: Second ZIP/postal code, same format rules as zip1.
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Response format. Anything other than `json` (including omitted) returns XML.
          schema:
            type: string
            enum: [xml, json]
            default: xml
      responses:
        "200":
          description: >
            Always returns HTTP 200. Successful requests and errors are both
            distinguished by the response body, not by HTTP status.
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/DistanceResultXml'
              examples:
                success:
                  summary: Successful result
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <results>
                      <zip1>12345</zip1>
                      <zip2>90210</zip2>
                      <distance>2448.4</distance>
                    </results>
                error:
                  summary: Error result
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <results>
                      <error>Description of the error</error>
                    </results>
            application/json:
              schema:
                $ref: '#/components/schemas/DistanceResultJson'
              examples:
                success:
                  summary: Successful result
                  value:
                    results:
                      zip1: "12345"
                      zip2: "90210"
                      distance: "2,448.4"
                error:
                  summary: Error result
                  value:
                    results:
                      error: Description of the error

components:
  schemas:
    DistanceResultXml:
      type: string
      description: XML document with a `<results>` root containing either the fields below or a single `<error>` element.

    DistanceResultJson:
      type: object
      properties:
        results:
          oneOf:
            - type: object
              properties:
                zip1:
                  type: string
                zip2:
                  type: string
                distance:
                  type: string
                  description: >
                    Great Circle distance in miles, formatted to one decimal
                    place with a thousands separator (e.g. "2,448.4").
            - type: object
              properties:
                error:
                  type: string

x-notes:
  - "Possible error messages: '{zip} is not a recognizable ZIP code.' (not 5 or 7 characters after normalization), 'You did not provide ZIP code 1.', 'You did not provide ZIP code 2.', '{key} is not a recognizable API key.', 'You did not provide an API key.', '{zip} is not a valid ZIP code.' (not found, or found with zero lat/lon), plus the shared account-limit errors (invalid API key, daily call limit exceeded, failed billing reverted to free tier, abusive account, IP shared across free accounts)."
  - "Distance formula is the standard spherical law of cosines using Earth radius 3958.75 miles."
