Skip to main content
GET
/
api
/
v1
/
ubigeos
/
search
Ubigeo Management
curl --request GET \
  --url https://api.example.com/api/v1/ubigeos/search
{
  "success": true,
  "data": {
    "id": "<string>",
    "nombre": "<string>",
    "provincia_id": "<string>",
    "provincia": "<string>",
    "region_id": "<string>",
    "region": "<string>",
    "ubigeo_completo": "<string>"
  }
}

Overview

The Ubigeo API provides access to Peru’s official geographic location codes (Códigos de Ubigeo) as defined by INEI (Instituto Nacional de Estadística e Informática). These codes are required for electronic invoicing to specify business and customer addresses.

What is Ubigeo?

Ubigeo is a 6-digit code that uniquely identifies geographic locations in Peru:
  • First 2 digits: Region/Department (e.g., “15” for Lima)
  • Next 2 digits: Province (e.g., “01” for Lima Province)
  • Last 2 digits: District (e.g., “01” for Lima District)
Example: 150101 = Lima > Lima > Lima
Ubigeo codes are mandatory in SUNAT electronic documents for specifying company addresses, branch locations, and customer addresses.

Search Ubigeo

Searches for ubigeo codes by name or partial text. Returns matching districts with their complete hierarchical information.

Query Parameters

q
string
required
Search query (minimum 2 characters, maximum 255 characters)
region_id
string
Optional filter by region ID (6 characters)
provincia_id
string
Optional filter by province ID (6 characters)
The search is performed against district names and includes fuzzy matching for better results. Returns up to 20 results.

Response

success
boolean
Indicates if the request was successful
data
array
Array of matching districts
id
string
Ubigeo code (6 digits)
nombre
string
District name
provincia
string
Province name
region
string
Region/Department name
ubigeo_completo
string
Full location path (Region - Province - District)

Example Request

curl -X GET "https://api.example.com/api/v1/ubigeos/search?q=miraflores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "150122",
      "nombre": "Miraflores",
      "provincia": "Lima",
      "region": "Lima",
      "ubigeo_completo": "Lima - Lima - Miraflores"
    },
    {
      "id": "130108",
      "nombre": "Miraflores",
      "provincia": "Huamalíes",
      "region": "Huánuco",
      "ubigeo_completo": "Huánuco - Huamalíes - Miraflores"
    },
    {
      "id": "200805",
      "nombre": "Miraflores",
      "provincia": "Huaraz",
      "region": "Áncash",
      "ubigeo_completo": "Áncash - Huaraz - Miraflores"
    }
  ]
}

Get Regions

Retrieves all regions (departments) in Peru.

Response

success
boolean
Indicates if the request was successful
data
array
Array of regions
id
string
Region code (6 digits, last 4 are “0000”)
nombre
string
Region name

Example Request

curl -X GET "https://api.example.com/api/v1/ubigeos/regiones" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "010000",
      "nombre": "Amazonas"
    },
    {
      "id": "020000",
      "nombre": "Áncash"
    },
    {
      "id": "030000",
      "nombre": "Apurímac"
    },
    {
      "id": "040000",
      "nombre": "Arequipa"
    },
    {
      "id": "150000",
      "nombre": "Lima"
    },
    {
      "id": "250000",
      "nombre": "Ucayali"
    }
  ]
}

Get Provinces

Retrieves provinces, optionally filtered by region.

Query Parameters

region_id
string
Filter by region ID (6 characters). If not provided, returns all provinces.

Response

success
boolean
Indicates if the request was successful
data
array
Array of provinces
id
string
Province code (6 digits, last 2 are “00”)
nombre
string
Province name
region_id
string
Parent region code
region
object
Parent region information
id
string
Region code
nombre
string
Region name

Example Request

curl -X GET "https://api.example.com/api/v1/ubigeos/provincias?region_id=150000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "150100",
      "nombre": "Lima",
      "region_id": "150000",
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150200",
      "nombre": "Barranca",
      "region_id": "150000",
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150300",
      "nombre": "Cajatambo",
      "region_id": "150000",
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    }
  ]
}

Get Districts

Retrieves districts with optional filtering by province, region, or search text.

Query Parameters

provincia_id
string
Filter by province ID (6 characters)
region_id
string
Filter by region ID (6 characters)
Search by district name (minimum 2 characters, maximum 255 characters)

Response

success
boolean
Indicates if the request was successful
data
array
Array of districts
id
string
District ubigeo code (6 digits)
nombre
string
District name
provincia_id
string
Province code
region_id
string
Region code
provincia
object
Province information
id
string
Province code
nombre
string
Province name
region
object
Region information
id
string
Region code
nombre
string
Region name

Example Request

curl -X GET "https://api.example.com/api/v1/ubigeos/distritos?provincia_id=150100&search=san" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "150130",
      "nombre": "San Borja",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150131",
      "nombre": "San Isidro",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150137",
      "nombre": "San Juan de Lurigancho",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150132",
      "nombre": "San Juan de Miraflores",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150133",
      "nombre": "San Luis",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150134",
      "nombre": "San Martín de Porres",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    },
    {
      "id": "150135",
      "nombre": "San Miguel",
      "provincia_id": "150100",
      "region_id": "150000",
      "provincia": {
        "id": "150100",
        "nombre": "Lima"
      },
      "region": {
        "id": "150000",
        "nombre": "Lima"
      }
    }
  ]
}

Get Ubigeo by ID

Retrieves detailed information for a specific ubigeo code.

Path Parameters

id
string
required
The 6-digit ubigeo code

Response

success
boolean
Indicates if the request was successful
data
object
id
string
Ubigeo code (6 digits)
nombre
string
District name
provincia_id
string
Province code
provincia
string
Province name
region_id
string
Region code
region
string
Region name
ubigeo_completo
string
Full location path (Region - Province - District)

Example Request

curl -X GET "https://api.example.com/api/v1/ubigeos/150122" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": {
    "id": "150122",
    "nombre": "Miraflores",
    "provincia_id": "150100",
    "provincia": "Lima",
    "region_id": "150000",
    "region": "Lima",
    "ubigeo_completo": "Lima - Lima - Miraflores"
  }
}

Error Responses

Invalid Ubigeo Length

{
  "success": false,
  "message": "El código de ubigeo debe tener exactamente 6 dígitos"
}

Ubigeo Not Found

{
  "success": false,
  "message": "Ubigeo no encontrado"
}

Validation Error

{
  "success": false,
  "message": "Errores de validación",
  "errors": {
    "q": [
      "El campo de búsqueda es requerido",
      "La búsqueda debe tener al menos 2 caracteres"
    ]
  }
}

Common Ubigeo Codes

  • 150101: Lima - Lima - Lima (Centro)
  • 150122: Lima - Lima - Miraflores
  • 150130: Lima - Lima - San Borja
  • 150131: Lima - Lima - San Isidro
  • 150140: Lima - Lima - Surco
  • 150141: Lima - Lima - Surquillo
  • 150143: Lima - Lima - La Molina
  • 040101: Arequipa - Arequipa - Arequipa
  • 130101: La Libertad - Trujillo - Trujillo
  • 080101: Cusco - Cusco - Cusco
  • 200101: Piura - Piura - Piura
  • 140101: Lambayeque - Chiclayo - Chiclayo

Implementation Guide

To build a hierarchical location selector (Region > Province > District):
  1. Load Regions: Call GET /api/v1/ubigeos/regiones to populate the region dropdown
  2. Load Provinces: When user selects a region, call GET /api/v1/ubigeos/provincias?region_id={region_id}
  3. Load Districts: When user selects a province, call GET /api/v1/ubigeos/distritos?provincia_id={provincia_id}
  4. Store the Ubigeo: Save the 6-digit district code from the final selection
For a simpler user experience with autocomplete:
  1. Implement a search input field
  2. Call GET /api/v1/ubigeos/search?q={query} as the user types (minimum 2 characters)
  3. Display results showing the full path (Region - Province - District)
  4. Store the selected ubigeo code
This is faster for users who know their location name.
When receiving ubigeo codes from external sources:
  1. Verify the code is exactly 6 digits
  2. Call GET /api/v1/ubigeos/{id} to validate it exists
  3. Display the full location name for user confirmation
  4. Store both the code and the location name for reference

Best Practices

Always store the 6-digit ubigeo code, not just the location names. Names can have variations, but codes are standardized.
Include ubigeo in all address records for companies, branches, and customers. This is required for SUNAT electronic documents.
Use the search endpoint for better UX when you have many locations. It provides fuzzy matching and quick results.
Ubigeo codes are maintained by INEI and rarely change, but periodically sync your local database with the API to ensure you have the latest codes.

Integration with Electronic Documents

Ubigeo codes are used in several places within electronic documents:
  • Company Address: Main business location (required)
  • Branch Address: Each branch/establishment location (required)
  • Customer Address: Buyer’s location (required for some document types)
  • Delivery Address: Destination in delivery guides (required for guías de remisión)
Example usage in an invoice:
{
  "company": {
    "ruc": "20123456789",
    "razon_social": "Mi Empresa SAC",
    "direccion": "Av. Principal 123",
    "ubigeo": "150122",
    "departamento": "Lima",
    "provincia": "Lima",
    "distrito": "Miraflores"
  },
  "customer": {
    "tipo_documento": "6",
    "numero_documento": "20987654321",
    "razon_social": "Cliente SAC",
    "direccion": "Jr. Comercio 456",
    "ubigeo": "150131"
  }
}

Build docs developers (and LLMs) love