> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postcode.gov.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Graded postcode lookup (levels 1–5, cumulative)



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/lookup
openapi: 3.1.0
info:
  title: NIPOST Postcode Gateway — Public API
  version: 0.1.0
  description: >
    Public API for Nigeria's national postcode system. Search and Lookup L1 are
    free; Lookup L2–L4 are commercial (credits); L5 is restricted. Authenticate
    with an API key.
servers:
  - url: https://api.postcode.gov.ng
    description: Production
  - url: http://localhost:8081
    description: Local gateway
security:
  - ApiKeyAuth: []
paths:
  /v1/lookup:
    get:
      summary: Graded postcode lookup (levels 1–5, cumulative)
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
        - name: level
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5
            default: 1
      responses:
        '200':
          description: Graded attributes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LookupResponse'
components:
  schemas:
    LookupResponse:
      type: object
      properties:
        postcode:
          type: string
        valid:
          type: boolean
        administrative_address:
          type: object
          description: L2+
        recent_house_address:
          type: object
          description: L2+
        building_use_status:
          type: string
          description: L3+
        other_building_info:
          type: object
          description: L4+
        point_geometry:
          type: object
          description: L5
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````