{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/postalkit.mx" } ], "info": { "name": "Laravel API Documentation", "_postman_id": "60905ecb-42e6-4e7c-a887-b97f69fe04ad", "description": "A fast, reliable REST API for looking up Mexican postal codes (c\u00f3digos postales) and address data.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "General", "description": "", "item": [ { "name": "GET api\/health", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/health", "query": [], "raw": "{{baseUrl}}\/api\/health" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "DENY" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "camera=(), microphone=(), geolocation=()" }, { "key": "strict-transport-security", "value": "max-age=31536000; includeSubDomains" }, { "key": "access-control-allow-origin", "value": "https:\/\/postalkit.mx" }, { "key": "access-control-expose-headers", "value": "X-RateLimit-Limit, X-RateLimit-Remaining" } ], "code": 200, "body": "{\"status\":\"ok\",\"service\":\"CodigoPostal MX API\",\"version\":\"1.0.0\",\"timestamp\":\"2026-05-13T15:52:18+00:00\"}", "name": "" } ] } ] }, { "name": "Postal Codes", "description": "\nLook up Mexican postal codes and their settlements, municipality, state, and city from the\nofficial SEPOMEX catalog.", "item": [ { "name": "Search postal codes by state, municipality, and\/or colonia", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/postal-codes\/search", "query": [ { "key": "state", "value": "Jalisco", "description": "State name to search.", "disabled": false }, { "key": "municipality", "value": "Guadalajara", "description": "Optional municipality name filter.", "disabled": false }, { "key": "colonia", "value": "Centro", "description": "Optional settlement (colonia) name filter.", "disabled": false }, { "key": "exact", "value": "1", "description": "Use exact matching instead of fuzzy (default: false).", "disabled": false }, { "key": "page", "value": "1", "description": "Page number (20 results per page).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/postal-codes\/search?state=Jalisco&municipality=Guadalajara&colonia=Centro&exact=1&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"state\":\"bngzmiyvdljnikhw\",\"municipality\":\"aykcmyuwpwlvqwrs\",\"colonia\":\"itcpscqldzsnrwtu\",\"exact\":false}" }, "description": "Search for postal codes using geographic filters. Supports both fuzzy (LIKE) and exact\nmatching via the `exact` parameter. Returns paginated results ordered by code." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":3,\"code\":\"44100\",\"state\":{\"id\":1,\"name\":\"Jalisco\",\"code\":\"14\"},\"municipality\":{\"id\":2,\"name\":\"Guadalajara\",\"code\":\"039\"},\"city\":{\"id\":1,\"name\":\"Guadalajara\"},\"settlements\":[{\"id\":5,\"name\":\"Centro\",\"type\":\"Colonia\",\"postal_code\":\"44100\"}]}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"total\":1,\"per_page\":20}}", "name": "Results" }, { "header": [], "code": 422, "body": "{\"message\":\"The given data was invalid.\",\"errors\":{\"state\":[\"The \\\"state\\\" query parameter is required.\"]}}", "name": "Missing state" } ] }, { "name": "Exact postal code lookup", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/postal-codes\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/postal-codes\/:code", "variable": [ { "id": "code", "key": "code", "value": "06600", "description": "The 5-digit postal code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the full record for a specific 5-digit postal code, including state, municipality,\ncity, and all settlements (colonias) that share that code.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":3,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"},\"city\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\"},\"settlements\":[{\"id\":5,\"name\":\"Roma Sur\",\"type\":\"Colonia\",\"postal_code\":\"06600\"}]}}", "name": "Found" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 404, "body": "{\"message\":\"Postal code '99999' not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\":\"Postal code must be exactly 5 digits.\"}", "name": "Invalid format" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] }, { "name": "Settlements for a postal code", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/postal-codes\/:code\/settlements", "query": [], "raw": "{{baseUrl}}\/api\/v1\/postal-codes\/:code\/settlements", "variable": [ { "id": "code", "key": "code", "value": "06600", "description": "The 5-digit postal code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve all settlements (colonias) that belong to a specific 5-digit postal code.\nReturns a slim payload without full postal code details.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":5,\"name\":\"Roma Sur\",\"zone\":\"Urbano\",\"settlement_type\":{\"id\":1,\"name\":\"Colonia\"}}]}", "name": "Found" }, { "header": [], "code": 404, "body": "{\"message\":\"Postal code '99999' not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\":\"Postal code must be exactly 5 digits.\"}", "name": "Invalid format" } ] }, { "name": "Geocode by postal code", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/postal-codes\/:code\/geocode", "query": [ { "key": "street", "value": "Reforma", "description": "Optional street name for reference.", "disabled": false }, { "key": "number", "value": "100", "description": "Optional street number for reference.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/postal-codes\/:code\/geocode?street=Reforma&number=100", "variable": [ { "id": "code", "key": "code", "value": "06600", "description": "The 5-digit postal code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the full record for a specific 5-digit postal code with geographic coordinates.\nOptional `street` and `number` query parameters are included in the response for reference\nbut do not affect the returned coordinates.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":3,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de Mexico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauhtemoc\",\"code\":\"015\"},\"city\":null,\"settlements\":[],\"latitude\":\"19.4233000\",\"longitude\":\"-99.1637000\",\"geocoded_street\":null,\"geocoded_number\":null}}", "name": "Found" }, { "header": [], "code": 404, "body": "{\"message\":\"Postal code '99999' not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\":\"Postal code must be exactly 5 digits.\"}", "name": "Invalid format" } ] }, { "name": "Search postal codes by prefix", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/postal-codes", "query": [ { "key": "q", "value": "066", "description": "Numeric prefix to search. Must be at least 2 characters.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number (20 results per page).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/postal-codes?q=066&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Search for postal codes by numeric prefix (useful for autocomplete). Returns paginated\nresults ordered by code. Query must be at least 2 characters." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":3,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"},\"city\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\"}}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"total\":1,\"per_page\":20}}", "name": "Results" }, { "header": [], "code": 422, "body": "{\"message\":\"Query parameter \\\"q\\\" must be at least 2 characters.\"}", "name": "Query too short" } ] } ] }, { "name": "Settlements", "description": "\nSearch for Mexican settlements (colonias, fraccionamientos, ejidos, etc.) by name.", "item": [ { "name": "Search settlements by name", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/settlements", "query": [ { "key": "q", "value": "Roma", "description": "Partial name of the settlement to search for.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number (20 results per page).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/settlements?q=Roma&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Full-text partial search across all settlement names in the SEPOMEX catalog. The search is\ncase-insensitive and matches anywhere in the name. Returns paginated results ordered\nalphabetically. Query must be at least 2 characters." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":5,\"name\":\"Roma Sur\",\"type\":\"Colonia\",\"postal_code\":\"06600\",\"municipality\":\"Cuauht\u00e9moc\",\"state\":\"Ciudad de M\u00e9xico\"}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"total\":2,\"per_page\":20}}", "name": "Results" }, { "header": [], "code": 422, "body": "{\"message\":\"Query parameter \\\"q\\\" must be at least 2 characters.\"}", "name": "Query too short" } ] } ] }, { "name": "States & Municipalities", "description": "\nBrowse the 32 Mexican states and their municipalities.", "item": [ { "name": "List all states", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the complete list of the 32 Mexican states (estados) ordered alphabetically.\nEach state includes its SEPOMEX state code." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":5,\"name\":\"Aguascalientes\",\"code\":\"01\"},{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"}]}", "name": "Success" } ] }, { "name": "List municipalities for a state by INEGI code", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states\/by-code\/:code\/municipalities", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states\/by-code\/:code\/municipalities", "variable": [ { "id": "code", "key": "code", "value": "09", "description": "The 2-digit INEGI state code (e.g. \"09\", \"14\")." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all municipalities (municipios) that belong to the state identified by its\n2-digit INEGI code, ordered alphabetically." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"\u00c1lvaro Obreg\u00f3n\",\"code\":\"010\"},{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"}]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"State with code '99' not found.\"}", "name": "State not found" } ] }, { "name": "List municipalities for a state", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states\/:id\/municipalities", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states\/:id\/municipalities", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the state (use `GET \/api\/v1\/states` to find IDs)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all municipalities (municipios) that belong to the given state, ordered alphabetically." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"\u00c1lvaro Obreg\u00f3n\",\"code\":\"010\"},{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"}]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"State with id 999 not found.\"}", "name": "State not found" } ] }, { "name": "List cities for a state", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states\/:id\/cities", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states\/:id\/cities", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the state (use `GET \/api\/v1\/states` to find IDs)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all cities (ciudades) that belong to the given state, ordered alphabetically." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Aguascalientes\"},{\"id\":2,\"name\":\"Calvillo\"}]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"State with id 999 not found.\"}", "name": "State not found" } ] }, { "name": "List postal codes for a state", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states\/:id\/postal-codes", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states\/:id\/postal-codes", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the state (use `GET \/api\/v1\/states` to find IDs)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all postal codes that belong to the given state, ordered by code and paginated." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"code\":\"01000\",\"state\":{\"id\":1,\"name\":\"Aguascalientes\"},\"municipality\":{\"id\":1,\"name\":\"Aguascalientes\"},\"city\":{\"id\":1,\"name\":\"Aguascalientes\"}}]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"State with id 999 not found.\"}", "name": "State not found" } ] }, { "name": "List settlements for a municipality within a state", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/states\/:id\/municipalities\/:mid\/settlements", "query": [], "raw": "{{baseUrl}}\/api\/v1\/states\/:id\/municipalities\/:mid\/settlements", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the state." }, { "id": "mid", "key": "mid", "value": "1", "description": "The numeric ID of the municipality." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all settlements that belong to the given municipality within the given state,\nordered alphabetically by name and paginated with 20 results per page." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Centro\",\"zone\":\"Urbano\",\"settlement_type\":{\"id\":1,\"name\":\"Colonia\"},\"postal_code\":{\"id\":1,\"code\":\"06600\"}}],\"links\":{},\"meta\":{\"current_page\":1,\"per_page\":20,\"total\":1}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"State with id 999 not found.\"}", "name": "State not found" }, { "header": [], "code": 404, "body": "{\"message\":\"Municipality with id 999 not found.\"}", "name": "Municipality not found" } ] } ] }, { "name": "Municipalities", "description": "\nBrowse municipality data including their postal codes.", "item": [ { "name": "List postal codes for a municipality", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/municipalities\/:id\/postal-codes", "query": [], "raw": "{{baseUrl}}\/api\/v1\/municipalities\/:id\/postal-codes", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the municipality." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all postal codes that belong to the given municipality, ordered by code\nand paginated with 20 results per page." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"},\"city\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\"}}],\"links\":{},\"meta\":{\"current_page\":1,\"per_page\":20,\"total\":1}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"Municipality with id 999 not found.\"}", "name": "Municipality not found" } ] }, { "name": "List settlements for a municipality", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/municipalities\/:id\/settlements", "query": [], "raw": "{{baseUrl}}\/api\/v1\/municipalities\/:id\/settlements", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The numeric ID of the municipality." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all settlements that belong to the given municipality (via their postal codes),\nordered alphabetically by name and paginated with 20 results per page." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Centro\",\"zone\":\"Urbano\",\"settlement_type\":{\"id\":1,\"name\":\"Colonia\"},\"postal_code\":{\"id\":1,\"code\":\"06600\"}}],\"links\":{},\"meta\":{\"current_page\":1,\"per_page\":20,\"total\":1}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\":\"Municipality with id 999 not found.\"}", "name": "Municipality not found" } ] } ] }, { "name": "Localities", "description": "\nSearch for localities (populated places) from the official INEGI catalog.", "item": [ { "name": "Search localities", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/localities", "query": [ { "key": "state", "value": "Jalisco", "description": "State name (fuzzy match). Required if not using codes.", "disabled": false }, { "key": "municipality", "value": "Guadalajara", "description": "Municipality name (fuzzy match). Required if not using codes.", "disabled": false }, { "key": "state_code", "value": "14", "description": "INEGI state code. Required if not using names.", "disabled": false }, { "key": "municipality_code", "value": "039", "description": "INEGI municipality code. Required if not using names.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number (20 results per page).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/localities?state=Jalisco&municipality=Guadalajara&state_code=14&municipality_code=039&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"state\":\"bngzmiyvdljnikhw\",\"municipality\":\"aykcmyuwpwlvqwrs\",\"state_code\":\"itcpscqldzsnrwtu\",\"municipality_code\":\"jwvlxjklqppwqbew\"}" }, "description": "Search for localities within a state and municipality. Supports two filter modes:\nby name (`state` + `municipality`) with fuzzy matching, or by INEGI code\n(`state_code` + `municipality_code`) with exact matching. Returns paginated results\nordered by name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"locality_code\":\"0001\",\"name\":\"Guadalajara\",\"ambito\":\"Urbano\",\"latitude\":\"20.6737800\",\"longitude\":\"-103.3442300\",\"altitude\":\"1566\",\"state\":{\"id\":1,\"name\":\"Jalisco\",\"code\":\"14\"},\"municipality\":{\"id\":2,\"name\":\"Guadalajara\",\"code\":\"039\"}}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"total\":1,\"per_page\":20}}", "name": "Results" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 422, "body": "{\"message\":\"The given data was invalid.\",\"errors\":{\"filter\":[\"You must provide either (state and municipality) or (state_code and municipality_code).\"]}}", "name": "Missing filter pair" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] }, { "name": "Get a locality", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/localities\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/localities\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The locality ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve a single locality by its ID, including state and municipality details." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"locality_code\":\"0001\",\"name\":\"Guadalajara\",\"ambito\":\"Urbano\",\"latitude\":\"20.6737800\",\"longitude\":\"-103.3442300\",\"altitude\":\"1566\",\"state\":{\"id\":1,\"name\":\"Jalisco\",\"code\":\"14\"},\"municipality\":{\"id\":2,\"name\":\"Guadalajara\",\"code\":\"039\"}}}", "name": "Found" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 404, "body": "{\"message\":\"Locality with id 99999 not found.\"}", "name": "Not found" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] } ] }, { "name": "Streets", "description": "\nSearch for streets and street types from the official INEGI catalog.", "item": [ { "name": "Search streets", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streets", "query": [ { "key": "state_code", "value": "09", "description": "The INEGI state code.", "disabled": false }, { "key": "municipality_code", "value": "015", "description": "The INEGI municipality code.", "disabled": false }, { "key": "locality_code", "value": "0001", "description": "Optional INEGI locality code to narrow results.", "disabled": false }, { "key": "q", "value": "Reforma", "description": "Optional street name search (partial match).", "disabled": false }, { "key": "limit", "value": "20", "description": "Results per page (max 100, default 50).", "disabled": false }, { "key": "page", "value": "1", "description": "Page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/streets?state_code=09&municipality_code=015&locality_code=0001&q=Reforma&limit=20&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"state_code\":\"bngzmiyvdljnikhw\",\"municipality_code\":\"aykcmyuwpwlvqwrs\",\"locality_code\":\"itcpscqldzsnrwtu\",\"q\":\"jwvlxjklqppwqbew\",\"limit\":6}" }, "description": "Search for streets within a state and municipality. Optionally filter by locality and\nstreet name. Returns paginated results ordered by name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Reforma\",\"code\":\"0001\",\"ambito\":\"Urbano\",\"street_type\":{\"id\":1,\"name\":\"Avenida\",\"code\":\"01\"},\"state\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"}}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"total\":1,\"per_page\":20}}", "name": "Results" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 422, "body": "{\"message\":\"The given data was invalid.\",\"errors\":{\"state_code\":[\"The \\\"state_code\\\" query parameter is required.\"]}}", "name": "Missing required params" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] }, { "name": "List street types", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/street-types", "query": [], "raw": "{{baseUrl}}\/api\/v1\/street-types" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the full catalog of street types (e.g. Avenida, Calle, Boulevard).\nReturns all types ordered by name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Avenida\",\"code\":\"01\"},{\"id\":2,\"name\":\"Boulevard\",\"code\":\"02\"},{\"id\":3,\"name\":\"Calle\",\"code\":\"03\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] } ] }, { "name": "Geocoding", "description": "\nReverse geocode coordinates to the nearest postal code.", "item": [ { "name": "Reverse geocode", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/geocode\/reverse", "query": [ { "key": "lat", "value": "19.4233", "description": "Latitude (-90 to 90).", "disabled": false }, { "key": "lng", "value": "-99.1637", "description": "Longitude (-180 to 180).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/geocode\/reverse?lat=19.4233&lng=-99.1637" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"lat\":-89,\"lng\":-179}" }, "description": "Find the nearest postal code to the given latitude and longitude coordinates." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":3,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de Mexico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauhtemoc\",\"code\":\"015\"},\"city\":null,\"settlements\":[],\"latitude\":\"19.4233000\",\"longitude\":\"-99.1637000\"}}", "name": "Found" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required.\"}", "name": "Unauthenticated" }, { "header": [], "code": 404, "body": "{\"message\":\"No geocoded postal codes found near the given coordinates.\"}", "name": "No results" }, { "header": [], "code": 422, "body": "{\"message\":\"The given data was invalid.\",\"errors\":{\"lat\":[\"The lat field is required.\"],\"lng\":[\"The lng field is required.\"]}}", "name": "Invalid params" } ] } ] }, { "name": "Account", "description": "\nInspect your account usage, plan limits, and database version information.", "item": [ { "name": "Get account usage", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/account\/usage", "query": [], "raw": "{{baseUrl}}\/api\/v1\/account\/usage" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the authenticated user's current plan, monthly request limit,\nusage count, and remaining requests for the current billing period." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"plan\":\"free\",\"monthly_limit\":100,\"usage_count\":42,\"remaining\":58,\"period\":\"2026-04\"}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] }, { "name": "Get database version", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/account\/db-version", "query": [], "raw": "{{baseUrl}}\/api\/v1\/account\/db-version" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the date of the last SEPOMEX database update and the current API version." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"last_updated\":\"2026-03-15T00:00:00.000000Z\",\"version\":\"1.0.0\"}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"error\":\"Unauthenticated\",\"message\":\"A valid API key is required. Pass it as: Authorization: Bearer {token}\"}", "name": "Unauthenticated" }, { "header": [], "code": 429, "body": "{\"error\":\"Too Many Requests\",\"message\":\"Rate limit exceeded. You are allowed 1 000 requests per hour.\",\"retry_after\":1800}", "name": "Rate limited" } ] } ] }, { "name": "Try it (no key needed)", "description": "\nA keyless, IP-rate-limited mirror of the production postal code lookup, used by the\ninteractive demo on the marketing site. Behaviour and response shape match\n`GET \/api\/v1\/postal-codes\/{code}`; the only differences are no Bearer token, a much\ntighter rate limit, and no usage metering.", "item": [ { "name": "Demo postal code lookup", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/demo\/postal-codes\/:code", "query": [], "raw": "{{baseUrl}}\/api\/demo\/postal-codes\/:code", "variable": [ { "id": "code", "key": "code", "value": "06600", "description": "The 5-digit postal code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the full record for a 5-digit postal code, including state, municipality, city,\nand all settlements (colonias). No API key required. Rate limited per IP address.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":3,\"code\":\"06600\",\"state\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\",\"code\":\"09\"},\"municipality\":{\"id\":2,\"name\":\"Cuauht\u00e9moc\",\"code\":\"015\"},\"city\":{\"id\":1,\"name\":\"Ciudad de M\u00e9xico\"},\"settlements\":[{\"id\":5,\"name\":\"Roma Sur\",\"zone\":\"Urbano\",\"settlement_type\":{\"id\":1,\"name\":\"Colonia\"}}]}}", "name": "Found" }, { "header": [], "code": 404, "body": "{\"message\":\"Postal code '00000' not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\":\"Postal code must be exactly 5 digits.\"}", "name": "Invalid format" }, { "header": [], "code": 429, "body": "{\"message\":\"Demo lookup limit reached. Sign up for a free key for 100 lookups every month.\"}", "name": "Demo limit reached" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }