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
string
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

Get started for freeTalk to us