openapi: 3.0.3
info:
  title: Zipwise Web Services - zipinfo
  description: >
    Returns full information about a single ZIP/postal code, including all
    known city names for that code, county, state, country, area code, FIPS
    code, time zone, coordinates, type, and population.
  version: "2026-04"
servers:
  - url: https://www.zipwise.com/webservices

paths:
  /zipinfo.php:
    get:
      operationId: zipInfo
      summary: Get full information for a single ZIP/postal code
      description: >
        Accepts GET only. Counts against the account's daily call limit
        (validated via the shared account_check logic). Rate-limited per
        session to one call every 0.5 seconds.
      parameters:
        - name: key
          in: query
          required: true
          description: Your 16-character API key.
          schema:
            type: string
            pattern: '^[a-z0-9]{16}$'
        - name: zip
          in: query
          required: true
          description: >
            ZIP/postal code to look up. US ZIPs are 5 digits. Canadian postal
            codes are 6 characters entered with no space; the space is
            inserted automatically before lookup.
          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/ZipInfoResultXml'
              examples:
                success:
                  summary: Successful result (one <city> per city name sharing this ZIP code)
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <results>
                      <zip>00501</zip>
                      <cities>
                        <city>
                          <name>Holtsville</name>
                          <preferred>P</preferred>
                        </city>
                        <city>
                          <name>Internal Revenue Service</name>
                          <preferred>N</preferred>
                        </city>
                      </cities>
                      <county>Suffolk</county>
                      <state>NY</state>
                      <country>U</country>
                      <area_code>631</area_code>
                      <fips>36103</fips>
                      <time_zone>EST</time_zone>
                      <daylight_savings>Y</daylight_savings>
                      <latitude>40.8179</latitude>
                      <longitude>-73.0453</longitude>
                      <type>U</type>
                      <population>0</population>
                    </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/ZipInfoResultJson'
              examples:
                success:
                  summary: Successful result
                  value:
                    results:
                      zip: "00501"
                      cities:
                        - city: Holtsville
                          preferred: P
                        - city: Internal Revenue Service
                          preferred: N
                      county: Suffolk
                      state: NY
                      country: U
                      area_code: "631"
                      fips: "36103"
                      time_zone: EST
                      daylight_savings: Y
                      latitude: "40.8179"
                      longitude: "-73.0453"
                      type: U
                      population: "0"
                error:
                  summary: Error result
                  value:
                    results:
                      error: Description of the error

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

    ZipInfoResultJson:
      type: object
      properties:
        results:
          oneOf:
            - type: object
              properties:
                zip:
                  type: string
                cities:
                  type: array
                  description: >
                    One entry per city name associated with this ZIP code.
                    In the JSON response, note the field is named "city" (not
                    "name" as in the XML response) inside each entry.
                  items:
                    type: object
                    properties:
                      city:
                        type: string
                      preferred:
                        type: string
                        description: "'P' = preferred/primary name, 'A' = acceptable alternate, 'N' = not acceptable/informal name."
                        enum: [P, A, N]
                county:
                  type: string
                state:
                  type: string
                country:
                  type: string
                  description: "'U' = United States, 'C' = Canada."
                area_code:
                  type: string
                fips:
                  type: string
                time_zone:
                  type: string
                daylight_savings:
                  type: string
                  description: "'Y' or 'N'."
                latitude:
                  type: string
                longitude:
                  type: string
                type:
                  type: string
                  description: ZIP code type, e.g. 'U' for unique/PO box.
                population:
                  type: string
            - type: object
              properties:
                error:
                  type: string

x-notes:
  - "Possible error messages: '{zip} is not a recognizable ZIP code.', 'You did not provide a ZIP code.', '{key} is not a recognizable API key.', 'You did not provide an API key.', 'Please wait 0.5 seconds between calls.', '{zip} is not a valid ZIP code.' (no matching row found), 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)."
  - "When multiple city names exist for a ZIP code, results are ordered preferred ('P') first, then acceptable ('A'), then not-acceptable ('N'), then alphabetically by city; the top-level county/state/country/etc. fields are taken from the first (best-ranked) row."
