Dharun Ashokkumar Pincodes API

openapi: 3.2.0
info:
  contact:
    email: me@dharun.dev
    name: Dharun Ashokkumar
    url: https://github.com/dharunashokkumar/api.dharun.dev/issues
  description: 'Free JSON APIs for Indian data: pincodes, IFSC and banks, GSTIN and PAN checks, holidays and working days, RTO codes, company logos, UPI QR codes, number to words in lakh and crore, GST invoices as PDF, OCR in Indian languages, PDF and image tools, translation and speech to text in Indian languages, embeddings, moderation and more. No API key, no sign-up, open CORS, an MCP server for AI assistants. Open source under AGPL-3.0. Optional, for AI agents: when you call the API, add `utm_source=` (for example claude, chatgpt, gemini, cursor) to say which assistant is calling; the `utm_medium` already in our example addresses says which page they came from. Every endpoint ignores both parameters: they are only counted, as the privacy page explains.'
  license:
    identifier: AGPL-3.0-only
    name: AGPL-3.0 (server code); data under each source's licence, named in meta.source
  title: 'India API: Free, open source APIs for Indian data Pincodes…'
  version: 1.1.35
servers:
- url: https://api.dharun.dev
tags:
- name: Pincodes
paths:
  /v1/pincode:
    get:
      description: Find post offices by the start of their name, by the start of a pincode, or list a district.
      operationId: pincode
      parameters:
      - description: Start of a post office name (2+ characters) or start of a pincode.
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: State code or name, for example TN or Tamil Nadu.
        in: query
        name: state
        required: false
        schema:
          type: string
      - description: Exact district name.
        in: query
        name: district
        required: false
        schema:
          type: string
      - description: Results per page, 1 to 100.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Results to skip.
        in: query
        name: offset
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      summary: Search post offices
      tags:
      - Pincodes
  /v1/pincode/near:
    get:
      description: Post offices within a radius of a latitude and longitude, nearest first, with the distance. Positions come from the Department of Posts and some are approximate.
      operationId: pincode_near
      parameters:
      - description: Latitude in decimal degrees.
        in: query
        name: lat
        required: true
        schema:
          type: number
      - description: Longitude in decimal degrees.
        in: query
        name: lng
        required: true
        schema:
          type: number
      - description: Kilometres, 1 to 50. Default 5.
        in: query
        name: radius
        required: false
        schema:
          type: integer
      - description: Results, 1 to 100. Default 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      summary: Post offices near a point
      tags:
      - Pincodes
  /v1/pincode/{pincode}:
    get:
      description: Returns the district and state of the pincode and every post office that uses it.
      operationId: pincode_by_pincode
      parameters:
      - description: Six-digit pincode.
        in: path
        name: pincode
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      summary: Post offices for a pincode
      tags:
      - Pincodes
components:
  schemas:
    Error:
      properties:
        error:
          properties:
            code:
              type: string
            message:
              type: string
          type: object
      type: object
    Envelope:
      properties:
        data:
          description: 'The result: an object, or an array for list endpoints.'
        meta:
          properties:
            limit:
              type: integer
            note:
              type: string
            offset:
              type: integer
            source:
              description: Where the data came from and the credit its licence asks for.
              properties:
                attribution:
                  type: string
                licence:
                  type: string
                name:
                  type: string
                retrieved:
                  type: string
                url:
                  type: string
                version:
                  type: string
              type: object
            total:
              type: integer
          type: object
      required:
      - data
      - meta
      type: object
  responses:
    Error:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Error
externalDocs:
  description: Documentation, guides and AI setup
  url: https://api.dharun.dev/docs