api-ninjas-com PIN Code API

openapi: 3.2.0
info:
  title: Ninjas PIN Code API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: PIN Code
  description: The PIN Code API looks up Indian PIN codes (Postal Index Numbers) and returns the city, district, state and coordinates. One PIN code often covers several post offices and localities, so responses are always an array. For postal codes outside India, use the Postal Code API.
paths:
  /v1/pincode:
    get:
      summary: Look up an Indian PIN code
      description: Returns the locations matching a six-digit Indian PIN code. Spaces and hyphens are normalized, so 110001, 110 001 and 110-001 all resolve. Searching by city, district or state instead of a pincode requires premium.
      operationId: getPinCode
      tags:
      - PIN Code
      parameters:
      - name: pincode
        in: query
        description: The six-digit Indian PIN code (Postal Index Number) to look up.
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: Post office or locality name to search in reverse, as returned in the city field, e.g. Connaught Place. To list a whole city, use district. Premium only.
        required: false
        schema:
          type: string
      - name: district
        in: query
        description: District to search in reverse, e.g. Pune. Premium only.
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: State or union territory to search in reverse, e.g. Maharashtra. Premium only.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PinCodeInfo'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinCodeOpenapi_Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinCodeOpenapi_Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinCodeOpenapi_Error'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    PinCodeOpenapi_Error:
      type: object
      properties:
        message:
          type: string
    PinCodeInfo:
      type: object
      properties:
        pincode:
          type: string
          example: '110001'
        city:
          type: string
          description: Post office or locality the row covers.
          example: New Delhi G.P.O.
        state:
          type: string
          example: Delhi
        state_code:
          type: string
          description: Numeric state code. Premium only.
          example: '07'
        district:
          type: string
          description: Premium only.
          example: New Delhi
        district_code:
          type: string
          description: Numeric district code. Premium only.
          example: 094
        lat:
          type: string
          description: Premium only.
          example: '28.6369'
        lon:
          type: string
          description: Premium only.
          example: '77.2183'
        accuracy:
          type: integer
          description: 'How precise the coordinates are, from 1 to 6 (higher is more precise): 6 = centroid of addresses or shape, 4 = gazetteer match, 1 = estimated. Published rather than implying uniform precision. Premium only.'
          example: 3
        timezone:
          type: string
          example: Asia/Kolkata
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api