API Reference
Complete reference for all Cambodia Postal Code API endpoints
Overview
The Cambodia Postal Code API exposes 10 endpoints covering provinces, districts, communes, villages, full-text search, and postal code lookup. All endpoints are under the base URL and require an API key.
Base URL
| Environment | Base URL |
|---|---|
| Production | https://api.cambodiapostalcode.com/v1 |
All examples in this reference use this base URL.
Authentication
All requests require an API key passed via the x-api-key header:
x-api-key: YOUR_API_KEYSee Authentication for details on obtaining and managing API keys.
Response Format
Every response uses a consistent envelope:
{
"statusCode": 200,
"data": { ... },
"metadata": {
"correlationId": "01a0642a-d55f-70f8-b40f-2ce1c5c12035"
}
}statusCode— HTTP status code echoed in the body (200 on success).data— The response payload. Shape varies per endpoint (see individual endpoint pages for schemas and examples).metadata.correlationId— UUIDv7 tracing ID. Include it when contacting support so we can locate the exact request in logs.
Errors replace data with an error object containing code, message, and
optional details. See Error Handling for
the full error format.
Localization
All list and detail endpoints accept a lang query parameter:
| Value | Language |
|---|---|
en | English (default) |
km | Khmer |
When lang=km, names and types are returned in Khmer script. Slugs and IDs
remain the same regardless of language.
OpenAPI Specification
OpenAPI Specification
Download the complete OpenAPI 3.0 specification for the Cambodia Postal Code API
JSON format compatible with Swagger UI, Postman, or code generators
View live spec from the API →Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /provinces | List all 25 provinces |
| GET | /provinces/{id} | Get a province by UUID, with district/commune/village counts |
| GET | /provinces/{id}/districts | List all districts in a province |
| GET | /districts/{id} | Get a district by UUID, with parent province info |
| GET | /districts/{id}/communes | List all communes in a district |
| GET | /communes/{id} | Get a commune by UUID, with parent hierarchy |
| GET | /communes/{id}/villages | List all villages in a commune |
| GET | /villages/{id} | Get a village by UUID, with full parent hierarchy |
| GET | /search | Full-text search across all units (paginated) |
| GET | /lookup/{postcode} | Reverse lookup by postal code → full hierarchy |
Browse each endpoint from the sidebar for detailed parameters, response schemas, and examples.