openapi: 3.1.0
info:
  title: Pincode API
  version: 1.0.0
  description: Read-only India PIN code and post-office API. The current public rate
    limit is 6 requests per 10 seconds per IP address. Successful responses use the
    stable success/data/meta V1 envelope.
  contact:
    email: api@pincodeapi.in
  termsOfService: https://pincodeapi.in/api-terms/
servers:
- url: https://api.pincodeapi.in/api/v1
externalDocs:
  description: Pincode API documentation
  url: https://pincodeapi.in/docs/
tags:
- name: System
  description: API discovery and service health.
- name: Postal lookup
  description: PIN code, state and district lookups.
- name: Search
  description: Post-office and postal-record search.
paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      tags:
      - System
      responses:
        '200':
          description: Service health information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
  /pincode/{pincode}:
    get:
      summary: Look up post offices for a PIN code
      operationId: getPincode
      tags:
      - Postal lookup
      parameters:
      - name: pincode
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{6}$
        description: Six-digit Indian PIN code.
      responses:
        '200':
          description: Matching post offices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PincodeSuccess'
        '400':
          description: Invalid PIN code.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: PIN code not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit reached.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /state/{state}:
    get:
      summary: Look up post offices in a state or Union Territory
      operationId: getState
      tags:
      - Postal lookup
      parameters:
      - name: state
        in: path
        required: true
        schema:
          type: string
        description: State or Union Territory name. URL-encode spaces and other reserved
          characters.
      responses:
        '200':
          description: Matching state-level postal information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        '404':
          description: State not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit reached.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /district/{district}:
    get:
      summary: Look up post offices in a district
      operationId: getDistrict
      tags:
      - Postal lookup
      parameters:
      - name: district
        in: path
        required: true
        schema:
          type: string
        description: District name. URL-encode spaces and other reserved characters.
      responses:
        '200':
          description: Matching district-level postal information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        '404':
          description: District not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit reached.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /search:
    get:
      summary: Search post offices and postal records
      operationId: searchPostOffices
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
        description: Post office, place, PIN, district or state search text supported
          by the service.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of search results to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
        description: Number of matching records to skip before returning results.
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSuccess'
        '400':
          description: Invalid search request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit reached.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    PostalRecord:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
        circle:
          type:
          - string
          - 'null'
        circle_slug:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        region_slug:
          type:
          - string
          - 'null'
        division:
          type:
          - string
          - 'null'
        division_slug:
          type:
          - string
          - 'null'
        office_name:
          type: string
        office_slug:
          type:
          - string
          - 'null'
        pincode:
          type: string
          pattern: ^[0-9]{6}$
        office_type:
          type:
          - string
          - 'null'
        delivery_status:
          type:
          - string
          - 'null'
        district:
          type:
          - string
          - 'null'
        district_slug:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        state_slug:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        digipin:
          type:
          - string
          - 'null'
    Meta:
      type: object
      properties:
        api_version:
          type: string
        dataset_version:
          type:
          - string
          - 'null'
        release_id:
          type:
          - string
          - 'null'
        request_id:
          type:
          - string
          - 'null'
        count:
          type:
          - integer
          - 'null'
        limit:
          type:
          - integer
          - 'null'
        offset:
          type:
          - integer
          - 'null'
    GenericSuccess:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          const: true
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    PincodeSuccess:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - pincode
          - post_offices
          properties:
            pincode:
              type: string
              pattern: ^[0-9]{6}$
            post_offices:
              type: array
              items:
                $ref: '#/components/schemas/PostalRecord'
        meta:
          $ref: '#/components/schemas/Meta'
    SearchSuccess:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            post_offices:
              type: array
              items:
                $ref: '#/components/schemas/PostalRecord'
            query:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    Problem:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
        request_id:
          type:
          - string
          - 'null'
