apiVersion: naftiko.dev/v1
kind: Capability
metadata:
  name: postalcodes-info-postal-code-reference-api
  title: PostalCodes.info Postal Code Reference API
  provider: postalcodes-info
  api: postal-code-reference-api
  version: '2026-05-05'
  tags:
    - Postal Codes
    - Geocoding
    - Open Data
    - Address Validation
    - Logistics
spec:
  description: |
    Shared per-API capability composition for the same-origin PostalCodes.info
    reference API. Exposes lookup search, country preview, country dataset
    downloads (CSV, XLSX, JSON) and canonical lookup pages used for citation
    and manual review.
  servers:
    - url: https://postalcodes.info
      description: Canonical production host
  references:
    openapi: ../../openapi/postalcodes-info-openapi.yml
    documentation: https://postalcodes.info/api
    license: https://opendatacommons.org/licenses/odbl/1-0/
  operations:
    - id: searchPostalCodes
      method: GET
      path: /search
      summary: Search Postal Codes, Places or Countries
      tags: [Search]
      inputs:
        q:
          type: string
          required: true
          minLength: 2
          description: Search term. Postal code, place name or country.
        country:
          type: string
          required: false
          pattern: ^[A-Za-z]{2}$
          description: Optional ISO 3166-1 alpha-2 country filter.
        region:
          type: string
          required: false
      outputs:
        suggestions:
          type: array
          schemaRef: ../../json-schema/postalcodes-info-search-suggestion-schema.json

    - id: previewCountryRecords
      method: GET
      path: /ajax-preview
      summary: Preview Records for One Country
      tags: [Search]
      inputs:
        country:
          type: string
          required: true
          description: Country slug such as spain, united-states, india.
      outputs:
        records:
          type: array
          schemaRef: ../../json-schema/postalcodes-info-postal-record-schema.json
      limits:
        maxRecords: 25000
        notes: Use country downloads for bulk imports instead of repeated previews.

    - id: createDownloadToken
      method: GET
      path: /download-token.php
      summary: Mint a Same-Origin Download Token
      tags: [Downloads]
      headers:
        X-Requested-With: XMLHttpRequest
        Referer: required
      outputs:
        token:
          type: string

    - id: downloadCountryDataset
      method: GET
      path: /download.php
      summary: Download a Country Dataset
      tags: [Downloads]
      inputs:
        country:
          type: string
          required: true
          pattern: ^[A-Za-z]{2}$
        format:
          type: string
          required: true
          enum: [csv, xlsx, json]
        t:
          type: string
          required: true
          description: Token from createDownloadToken.
      outputs:
        file:
          type: binary

    - id: getCountryLookupPage
      method: GET
      path: /postal-codes/{country}
      summary: Open a Country Postal-Code Reference Page
      tags: [Lookup Pages]
      inputs:
        country:
          type: string
          required: true
          description: Country slug.
      outputs:
        html:
          type: string

  policies:
    auth:
      type: none
      notes: Public reads. Downloads require same-origin token from createDownloadToken.
    rateLimits:
      reconciled: false
      notes: PostalCodes.info does not publish numeric per-key or per-IP limits.
    license:
      name: Open Database License (ODbL) 1.0
      attribution: 'Contains information from the Global Postal Code Repository (postalcodes.info), available under the Open Database License (ODbL).'