openapi: 3.1.0
info:
  title: PostalCodes.info Postal Code Reference Downloads Search API
  summary: Same-origin postal-code search, country export and lookup-page endpoints.
  description: PostalCodes.info exposes postal-code reference data for lookup, testing, education, geospatial examples and data-quality workflows. Coverage and granularity vary by country. This is not an official delivery-grade postal authority API; validate shipping, compliance and certified address decisions against the relevant national postal authority.
  version: '2026-05-05'
  contact:
    name: Pablo Cirre, PostalCodes.info
    url: https://postalcodes.info/contact
    email: social@genera.work
  license:
    name: Open Database License 1.0
    url: https://opendatacommons.org/licenses/odbl/1-0/
servers:
- url: https://postalcodes.info
  description: Canonical production host
tags:
- name: Search
  description: Interactive postal-code and locality lookup.
paths:
  /search:
    get:
      tags:
      - Search
      summary: Search Postal Codes, Places or Countries
      description: Returns lightweight suggestions used by the public lookup UI. Use country filtering when the user's country is known. Postal-code coverage and granularity vary by country.
      operationId: searchPostalCodes
      parameters:
      - name: q
        in: query
        required: true
        description: Search term. Minimum 2 characters.
        schema:
          type: string
          minLength: 2
          examples:
          - madrid
          - '28001'
          - '90210'
      - name: country
        in: query
        required: false
        description: Optional ISO 3166-1 alpha-2 country code filter.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
          examples:
          - ES
          - US
          - IN
      - name: region
        in: query
        required: false
        description: Optional region text filter.
        schema:
          type: string
      responses:
        '200':
          description: A list of matching country, locality or postal-code suggestions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchSuggestion'
              examples:
                madrid:
                  summary: Madrid lookup example
                  value:
                  - type: Town/City
                    text: Madrid
                    sub: Spain
                    url: /postal-codes/spain/madrid
  /ajax-preview:
    get:
      tags:
      - Search
      summary: Preview Records for One Country
      description: Returns up to 25,000 postal-code records for a country preview modal. For large imports, use country downloads instead of repeated live requests.
      operationId: previewCountryRecords
      parameters:
      - name: country
        in: query
        required: true
        description: Country slug such as spain, united-states or india.
        schema:
          type: string
          examples:
          - spain
          - united-states
          - india
      responses:
        '200':
          description: Preview rows for the requested country, or an error object if the country is invalid.
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/PostalRecord'
                - $ref: '#/components/schemas/Error'
components:
  schemas:
    PostalRecord:
      type: object
      properties:
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          examples:
          - ES
          - US
        postal_code:
          type: string
          description: Postal identifier as text. It may contain leading zeroes, spaces, letters or punctuation.
        place_name:
          type: string
        admin_name1:
          type:
          - string
          - 'null'
        admin_name2:
          type:
          - string
          - 'null'
        admin_name3:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
          description: Approximate locality or area centroid, not a delivery-point coordinate.
        longitude:
          type:
          - number
          - 'null'
          description: Approximate locality or area centroid, not a delivery-point coordinate.
    SearchSuggestion:
      type: object
      required:
      - type
      - text
      - sub
      - url
      properties:
        type:
          type: string
          examples:
          - Country
          - Town/City
          - Postal Code
        text:
          type: string
          examples:
          - Madrid
          - 90210 (Beverly Hills)
        sub:
          type: string
          examples:
          - Spain
          - United States
        url:
          type: string
          examples:
          - /postal-codes/spain/madrid
          - /postal-codes/united-states/code/90210
    Error:
      type: object
      properties:
        error:
          type: string