Colonias endpoint

GET /api/public/v1/mx/colonies?postal_code={postal_code}

Authentication

HTTP Basic Auth via ApiAccount, consistent with all other Public API endpoints.

Request

Parameter	Type	Required	Description
`postal_code`	string	Yes	5-digit Mexican postal code

Example:

GET /api/public/v1/mx/colonies?postal_code=36100
Authorization: Basic <credentials>

Response

200 OK

{
  "colonies": ["Barrio Nuevo", "Silao Centro", "Tierra y Libertad"],
  "municipality": "Silao de la Victoria",
  "city": "Silao de la Victoria",
  "state": "Guanajuato"
}

Field	Type	Description
colonies	string[]	List of colony names valid for this postal code
municipality	string	Municipality (municipio)
city	string	City name
state	string	State name

400 Bad Request — missing postal code

{
  "errors": [{ "code": "postal_code_required", "title": "postal_code is required" }]
}

400 Bad Request — invalid postal code

{
  "errors": [{ "code": "postal_code_invalid", "title": "invalid postal_code" }]
}

404 Not Found — postal code not found in Multiburó

{
  "colonies": [],
  "municipality": null,
  "city": null,
  "state": null
}

401 Unauthorized

Standard HTTP Basic Auth denial (Rails default):

HTTP Basic: Access denied.

502 Bad Gateway — Multiburó service error

{
  "errors": [{ "code": "zipcode_service_error", "title": "Failed to fetch colonies" }]
}

504 Gateway Timeout — Multiburó service timeout

{
  "errors": [{ "code": "zipcode_service_timeout", "title": "Zip code service timeout" }]
}