LocatoMX API

Descripción general

LocatoMX es una solución RESTful desarrollada para proporcionar información precisa y actualizada sobre la división geográfica de México. Permite acceder a datos detallados de códigos postales, colonias, municipios y entidades federativas, lo que facilita la integración de funcionalidades de geolocalización en aplicaciones web y móviles.

Características principales

Consulta de códigos postales: Obtén información detallada sobre un código postal específico, incluyendo las colonias asociadas, el municipio y la entidad federativa correspondiente.
Búsqueda por nombre: Realiza búsquedas inteligentes por nombre de entidad federativa, municipio o colonia para obtener información relacionada.
Geocodificación: Convierte direcciones en coordenadas geográficas (latitud y longitud) para su uso en mapas y sistemas de ubicación.
Geocodificación inversa: Obtén la dirección correspondiente a unas coordenadas geográficas específicas.
Validación de direcciones: Verifica la existencia y exactitud de una dirección completa dentro del territorio mexicano.

Casos de Uso Comunes

E-commerce: Validación de direcciones de envío y cálculo de zonas de cobertura.
Aplicaciones de entrega: Determinación de rutas óptimas y asignación de pedidos según ubicación.
Sistemas de CRM: Enriquecimiento de datos de clientes con información geográfica detallada.
Análisis geoespacial: Estudios de mercado y segmentación geográfica basada en códigos postales.

Información para realizar consultas

Base URL

GET

Encabezados requeridos (Headers)

Key	Valor
`Accept`	application/json
`Content-Type`	application/json
`ApiKey`	4249cba5-**---**********

Necesitas una APIKEY para hacer uso de esta API. OBTENER TU APIKEY.

Paginación

Las respuestas de algunos endpoints utilizan paginación para devolver los resultados en bloques, facilitando la carga y el manejo de datos. Por defecto, se devuelven 50 objetos por página.

Estructura de la Paginación en la Respuesta JSON

Clave	Descripción	Ejemplo
`current_page`	Número de la página actual.	`1`
`data`	Arreglo con los registros de la página actual.	`[ { "uuid": "...", "codigo": "00000" }, ... ]`
`first_page_url`	URL de la primera página de resultados.	`codigos-postales?page=1`
`from`	Índice del primer elemento mostrado en esta página.	`1`
`next_page_url`	URL de la siguiente página. Si no hay más páginas, es `null`.	`codigos-postales?page=2`
`path`	URL base sin parámetros de paginación.	`codigos-postales`
`per_page`	Cantidad de registros devueltos por página (por defecto: 50).	`50`
`prev_page_url`	URL de la página anterior. Si es la primera página, es `null`.	`null`
`to`	Índice del último elemento mostrado en esta página.	`50`

Modificar página o cantidad de resultados:

Puedes personalizar la paginación usando estos parámetros:

?page=N: Especifica la página deseada. Ejemplo: ?page=2
?per_page=N: Cambia el número de resultados por página. Ejemplo: ?per_page=100

1. GET Listar todos los Estados

Este endpoint permite obtener un listado completo de los estados de la República Mexicana almacenados en el sistema. Es útil para autocompletado, filtros, o selección de datos geográficos.

Endpoint

GET /mx/info/estados

Campo	Descripción
`estados`	Endpoint.

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/estados' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Listado de estados obtenido correctamente.",
    "data": [
        {
            "uuid": "390f3419-410c-4a72-8c8e-1e268f212f93",
            "nombre": "AGUASCALIENTES"
        },
        {
            "uuid": "d572e14e-8214-4116-b8f2-7fc7ad32eb2e",
            "nombre": "BAJA CALIFORNIA"
        },
        // Más estados...
    ]
}

2. GET Listar todos los Municipios por Estado

Este endpoint permite obtener un listado completo de los municipios de un estado específico de la República Mexicana almacenados en el sistema. Es útil para autocompletado de direcciones, filtros de ubicación o selección de datos geográficos detallados.

Endpoint

GET /mx/info/estados/{uuid_estado}/municipios

Campo	Descripción	Requerido
`uuid_estado`	UUID del estado del cual se desean obtener los municipios.	Si

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/estados/7898bba7-0db2-4a5e-bc20-2a5a48f79fd6/municipios' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Listado de municipios obtenido correctamente.",
    "data": [
        {
            "uuid": "6a0cf899-3df1-4c16-bb7c-d54b82666a64",
            "nombre": "AGUASCALIENTES"
        },
        {
            "uuid": "2f0f4f79-2b6e-4db7-96fa-572dfa75c16d",
            "nombre": "ASIENTOS"
        },
        // Más municipios...
    ]
}

3. GET Listar Colonias por Municipio

Este endpoint permite obtener un listado completo de las colonias pertenecientes a un municipio específico de la República Mexicana almacenadas en el sistema. Es útil para autocompletado de direcciones, filtros o selección de datos geográficos detallados.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/municipios/{uuid_municipio}/colonias

Campo	Descripción	Requerido
`uuid_municipio`	UUID del municipio del cual se desean obtener las colonias.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/municipios/cb942b2e-0fc5-4848-8642-683f57d080f7/colonias' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias para el municipio 'AMACUZAC' obtenidas correctamente.",
    "data": [
        {
            "uuid": "b966c1e7-7163-4b01-965c-78d54b515bbd",
            "nombre": "AMACUZAC"
        },
        {
            "uuid": "b5cb82bc-0287-4354-89e6-2fc088490f66",
            "nombre": "BARREAL"
        }
        // Más colonias...
    ]
}

4. GET Listar todas las Colonias asociadas a un Código Postal específico

Este endpoint permite obtener un listado de todas las colonias correspondientes a un código postal específico en la República Mexicana. Es útil para funcionalidades de autocompletado, selección de dirección y validación de códigos postales.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/codigos-postales/{codigo_postal}/colonias

Campo	Descripción	Requerido
`codigo_postal`	Código postal (5 dígitos) del cual se desean obtener las colonias asociadas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/codigos-postales/62780/colonias' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias para el código postal '62780' obtenidas correctamente.",
    "data": [
        {
            "uuid": "43e20a1f-a097-4f6b-ae6a-c70bd28a1f4a",
            "nombre": "20 DE NOVIEMBRE"
        },
        {
            "uuid": "2f2b9982-4722-4d39-8349-fb7d69710eb8",
            "nombre": "BENITO JUÁREZ"
        }
        // Más colonias...
    ]
}

5. GET Listar todos los Tipos de Comunidad

Este endpoint permite obtener un listado de todos los tipos de comunidad disponibles en el sistema. Es útil para clasificar colonias, fraccionamientos, rancherías, entre otros, en formularios o procesos de captura de direcciones.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/tipos-comunidad

Campo	Descripción	Requerido
-	Este endpoint no requiere parámetros.	No

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/tipos-comunidad' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Listado de tipos de comunidad obtenido correctamente.",
    "data": [
        {
            "uuid": "38588e80-6ba4-4479-bec7-03452b12aa90",
            "nombre": "COLONIA"
        },
        {
            "uuid": "272f0b46-c2e8-4fa0-a76a-c4b41ef8830a",
            "nombre": "FRACCIONAMIENTO"
        }
        // Más tipos de comunidad...
    ]
}

6. GET Obtener Estado a partir de un Código Postal

Este endpoint permite obtener el estado correspondiente a un código postal específico. Es útil para determinar automáticamente el estado de una dirección con base en el código postal proporcionado.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/codigos-postales/{codigo_postal}/estado

Campo	Descripción	Requerido
`codigo_postal`	Código postal del cual se desea obtener el estado.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/codigos-postales/62780/estado' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Estado para el código postal 62780 encontrado.",
    "data": {
        "uuid": "7898bba7-0db2-4a5e-bc20-2a5a48f79fd6",
        "nombre": "MORELOS"
    }
}

7. GET Obtener Municipio y Estado a partir de una Colonia UUID

Este endpoint permite obtener el municipio y estado asociados a una colonia específica mediante su uuid. Es útil para obtener toda la ubicación geográfica detallada de una colonia.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/colonias/{colonia_uuid}/ubicacion

Campo	Descripción	Requerido
`colonia_uuid`	`UUID` de la colonia de la cual se desea obtener el municipio y estado asociados.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/colonias/66e97c6d-587c-4136-86b8-126f9ee57330/ubicacion' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Ubicación geográfica de la colonia obtenida correctamente.",
    "data": {
        "colonia": {
            "uuid": "66e97c6d-587c-4136-86b8-126f9ee57330",
            "nombre": "BENITO JUÁREZ"
        },
        "municipio": {
            "uuid": "cb942b2e-0fc5-4848-8642-683f57d080f7",
            "nombre": "AMACUZAC"
        },
        "estado": {
            "uuid": "7898bba7-0db2-4a5e-bc20-2a5a48f79fd6",
            "nombre": "MORELOS"
        }
    }
}

8. GET Obtener Colonias por Tipo de Comunidad

Este endpoint permite obtener todas las colonias asociadas a un determinado tipo de comunidad, como "Colonia" o "Fraccionamiento". Es útil para filtrar colonias por su categoría comunitaria.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/tipos-comunidad/{tipo_comunidad_uuid}/colonias

Campo	Descripción	Requerido
`tipo_comunidad_uuid`	`UUID` del tipo de comunidad del cual se desean obtener las colonias asociadas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/tipos-comunidad/38588e80-6ba4-4479-bec7-03452b12aa90/colonias' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias asociadas al tipo de comunidad 'COLONIA' obtenidas correctamente.",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 69999,
                "uuid": "a7ff9d61-4bd0-4a25-aef7-46ebffaaa947",
                "nombre": "\"Y\" GRIEGA",
                "tipos_comunidades_id": 1,
                "codigos_postales_municipios_id": 14297
            },
            {
                "id": 47148,
                "uuid": "1ab7c1e0-26e2-4af6-a3c2-1551c638dc9b",
                "nombre": "06 DE ABRIL",
                "tipos_comunidades_id": 1,
                "codigos_postales_municipios_id": 8259
            }
        ]
    }
}

9. GET Obtener Código Postal por UUID de Colonia

Este endpoint permite obtener el código postal correspondiente a una colonia específica utilizando su UUID. Es útil para validar o completar datos de dirección a partir de la colonia seleccionada.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/colonias/{colonia_uuid}/codigo-postal

Campo	Descripción	Requerido
`colonia_uuid`	`UUID` de la colonia para la cual se desea obtener el código postal.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/colonias/a7ff9d61-4bd0-4a25-aef7-46ebffaaa947/codigo-postal' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Código postal para la colonia '\"Y\" GRIEGA' encontrado.",
    "data": {
        "uuid": "6bcefe34-6084-4f74-a69d-141032039f7d",
        "codigo_postal": "54460"
    }
}

10. GET Listar todos los códigos postales disponibles

Este endpoint permite obtener un listado paginado de todos los códigos postales disponibles en la base de datos. Es útil para obtener un catálogo completo de códigos postales con su respectivo UUID.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/codigos-postales

Campo	Descripción	Requerido
`page`	Número de página para la paginación de resultados.	No

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/codigos-postales' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Lista de códigos postales obtenida correctamente.",
    "data": {
        "current_page": 1,
        "data": [
            {
                "uuid": "39c37ac5-d3d1-4be7-8d9c-55277df421cc",
                "codigo": "00000"
            },
            {
                "uuid": "c20c94de-ad38-4150-b607-0399a843cc0e",
                "codigo": "1000"
            }
        ],
        "first_page_url": "https://locatomx.kharmasolutions.com/mx/info/codigos-postales?page=1",
        "from": 1,
        "next_page_url": "https://locatomx.kharmasolutions.com/mx/info/codigos-postales?page=2",
        "path": "https://locatomx.kharmasolutions.com/mx/info/codigos-postales",
        "per_page": 50,
        "prev_page_url": null,
        "to": 50
    }
}

11. GET Buscar estado por nombre

Este endpoint permite buscar un estado específico por su nombre. El resultado incluye su UUID, nombre y un listado de municipios relacionados.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/estado?nombre={nombre}

Campo	Descripción	Requerido
`nombre`	Nombre del estado que se desea buscar. No es sensible a mayúsculas/minúsculas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/estado?nombre=jalisco' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Estados encontrados por nombre.",
    "data": [
        {
            "uuid": "354d4471-9c69-48d4-999b-38d3350651e3",
            "nombre": "JALISCO",
            "municipios": [
                {
                    "uuid": "1cd6a49f-d842-4d53-9923-029b5fd515a3",
                    "nombre": "GUADALAJARA"
                },
                {
                    "uuid": "bc9ac220-81d1-4fcc-affc-69e11b8135e8",
                    "nombre": "ZAPOPAN"
                }
            ]
        }
    ]
}

12. GET Buscar municipio por nombre

Este endpoint permite buscar municipios que coincidan con un nombre proporcionado. Los resultados incluyen su UUID, nombre y la información del estado al que pertenecen.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/municipio?nombre={nombre}

Campo	Descripción	Requerido
`nombre`	Nombre del municipio que se desea buscar. No es sensible a mayúsculas/minúsculas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/municipio?nombre=Zacatepec' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Municipios encontrados por nombre.",
    "data": [
        {
            "uuid": "712f4379-8098-4659-971e-ecbf34cb0eb8",
            "nombre": "SAN MARTÍN ZACATEPEC",
            "estado_pais": {
                "uuid": "7577399a-dbd9-4582-a930-1a1e3e060a2f",
                "nombre": "OAXACA"
            }
        },
        {
            "uuid": "940c0aa3-af6c-4ebf-9fd4-d8f93881c6f6",
            "nombre": "SANTA MARÍA ZACATEPEC",
            "estado_pais": {
                "uuid": "7577399a-dbd9-4582-a930-1a1e3e060a2f",
                "nombre": "OAXACA"
            }
        }
    ]
}

13. GET Buscar colonias por nombre

Este endpoint permite buscar colonias que coincidan con un nombre proporcionado. Los resultados incluyen su UUID, nombre, código postal, municipio y estado correspondiente. La respuesta está paginada.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/colonia?nombre={nombre}

Campo	Descripción	Requerido
`nombre`	Nombre de la colonia que se desea buscar. No es sensible a mayúsculas/minúsculas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/colonia?nombre=Zacatepec' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias encontradas por nombre.",
    "data": {
        "current_page": 1,
        "data": [
            {
                "uuid": "fed0d397-085a-4346-835b-39f03eb52653",
                "nombre": "DE ZACATEPEC",
                "codigo_postal_municipio": {
                    "uuid": "586ade40-9803-4c69-90d5-82b7a8eb75ef",
                    "codigo_postal": {
                        "uuid": "14119cb8-2316-4292-add9-1799e018b69e",
                        "codigo": "90425"
                    },
                    "municipio": {
                        "uuid": "a37d51e4-6f49-4102-8a03-17cc35c11c46",
                        "nombre": "MUÑOZ DE DOMINGO ARENAS",
                        "estado_pais": {
                            "uuid": "4d8c1965-4e50-4fb2-be9d-a0e6df341f6f",
                            "nombre": "TLAXCALA"
                        }
                    }
                }
            }
        ],
        "first_page_url": "https://locatomx.kharmasolutions.com/mx/info/buscar/colonia?page=1",
        "from": 1,
        "next_page_url": null,
        "path": "https://locatomx.kharmasolutions.com/mx/info/buscar/colonia",
        "per_page": 50,
        "prev_page_url": null,
        "to": 24
    }
}

14. GET Buscar colonias por código postal

Este endpoint permite buscar todas las colonias asociadas a un código postal específico. La respuesta incluye el UUID de la colonia, nombre, así como información del municipio y estado correspondiente.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/colonias-codigo?codigo={codigo_postal}

Campo	Descripción	Requerido
`codigo`	Código postal de 5 dígitos para buscar las colonias relacionadas.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/colonias-codigo?codigo=62780' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias encontradas para el código postal 62780.",
    "data": [
        {
            "uuid": "ebbef1d1-8b13-477f-bed7-486a13f1c539",
            "nombre": "TETELPA",
            "codigo_postal_municipio": {
                "uuid": "dd287798-2347-4604-af0f-f946d85c9a66",
                "municipio": {
                    "uuid": "ea0d30be-64cd-4dbc-9cb6-9db9862ec39e",
                    "nombre": "ZACATEPEC",
                    "estado_pais": {
                        "uuid": "7898bba7-0db2-4a5e-bc20-2a5a48f79fd6",
                        "nombre": "MORELOS"
                    }
                }
            }
        }
    ]
}

15. GET Buscar colonias por estado y municipio

Este endpoint permite obtener todas las colonias asociadas a un estado y municipio específicos. La consulta es sensible a los nombres exactos del estado y municipio proporcionados.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/colonias-por-ubicacion?estado={estado}&municipio={municipio}

Campo	Descripción	Requerido
`estado`	Nombre completo del estado.	Sí
`municipio`	Nombre completo del municipio dentro del estado especificado.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/colonias-por-ubicacion?estado=Morelos&municipio=Cuernavaca' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Colonias encontradas para CUERNAVACA, MORELOS.",
    "data": [
        {
            "uuid": "af74617a-9144-4064-8f74-2218d9d6cccc",
            "nombre": "ACAPATZINGO",
            "codigo_postal_municipio": {
                "uuid": "6c704367-01c7-414f-88db-f9b17d18e082",
                "codigo_postal": {
                    "uuid": "1072fd7d-2603-4b62-b474-39bd2557bafa",
                    "codigo": "62493"
                }
            }
        },
        {
            "uuid": "a7d59eb8-02b2-48e8-8d12-ffffbe56c363",
            "nombre": "ADOLFO LÓPEZ MATEOS",
            "codigo_postal_municipio": {
                "uuid": "bdd5b219-f6e5-4ea7-8b96-99058b8ce4bb",
                "codigo_postal": {
                    "uuid": "7f92c3c1-a2c4-47d2-968e-22e16a91bce8",
                    "codigo": "62115"
                }
            }
        }
    ]
}

16. GET Generar dirección completa a partir de código postal y colonia

Este endpoint permite obtener la dirección completa de una ubicación en México especificando el código postal y el nombre de la colonia. La respuesta incluye la colonia, código postal, municipio, estado y país.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/direccion/completa?codigo_postal={codigo_postal}&colonia={colonia}

Campo	Descripción	Requerido
`codigo_postal`	Código postal de la ubicación deseada.	Sí
`colonia`	Nombre de la colonia correspondiente al código postal.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/direccion/completa?codigo_postal=62780&colonia=TETELPA' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Dirección completa generada exitosamente.",
    "data": {
        "colonia": "TETELPA",
        "codigo_postal": "62780",
        "municipio": "ZACATEPEC",
        "estado": "MORELOS",
        "pais": "México"
    }
}

17. GET Obtener coordenadas geográficas a partir de una dirección

Este endpoint permite obtener las coordenadas geográficas (latitud y longitud) a partir de una dirección textual proporcionada. Utiliza un proceso de geocodificación para traducir la dirección en coordenadas precisas.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/geocodificar?direccion={direccion}

Campo	Descripción	Requerido
`direccion`	Texto de la dirección (calle, colonia, ciudad, etc.) a geocodificar.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/geocodificar?direccion=Tequesquitengo' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Coordenadas obtenidas exitosamente.",
    "data": {
        "locacion": "62909 Tequesquitengo, MOR, Mexico",
        "latitud": 18.6191125,
        "longitud": -99.2562099
    }
}

18. GET Obtener dirección a partir de coordenadas geográficas

Este endpoint permite obtener la dirección aproximada correspondiente a unas coordenadas geográficas (latitud y longitud). Utiliza un proceso de geocodificación inversa para convertir las coordenadas en una dirección legible.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/reversa-geocodificar?latitud={latitud}&longitud={longitud}

Campo	Descripción	Requerido
`latitud`	Latitud de la ubicación.	Sí
`longitud`	Longitud de la ubicación.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/reversa-geocodificar?latitud=18.92422841828199&longitud=-99.22160743233249' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Dirección obtenida exitosamente.",
    "data": {
        "direccion": "Avenida Teopanzolco, Jacarandas, 62420 Cuernavaca, MOR, Mexico"
    }
}

19. Buscar lugares por nombre

Este endpoint permite buscar lugares específicos a partir de un nombre o palabra clave. Resulta útil para encontrar ubicaciones aproximadas como tiendas, puntos de interés o establecimientos comerciales a nivel nacional.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/buscar/lugar?nombre={nombre}

Campo	Descripción	Requerido
`nombre`	Nombre del lugar o palabra clave a buscar.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/buscar/lugar?nombre=Costco' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Lugares encontrados exitosamente.",
    "data": {
        "error": false,
        "status_code": 200,
        "data": [
            {
                "locacion": "Costco, Centro, Mexico",
                "latitud": 17.9656498,
                "longitud": -92.9320538
            },
            {
                "locacion": "Costco, Chihuahua City, Municipio de Chihuahua, Mexico",
                "latitud": 28.6486173,
                "longitud": -106.1304031
            }
        ]
    }
}

20. Validar dirección completa

Este endpoint permite verificar la validez y obtener información geográfica detallada de una dirección proporcionada. Es útil para validar entradas de usuarios, mejorar precisión de datos y georreferenciar ubicaciones.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/validar/direccion?direccion={direccion}

Campo	Descripción	Requerido
`direccion`	Dirección completa que se desea validar.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/validar/direccion?direccion=Avenida%20Teopanzolco%2C%20Jacarandas%2C%2062420%20Cuernavaca%2C%20MOR%2C%20Mexico' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Dirección validada exitosamente.",
    "data": {
        "direccion_validada": "Avenida Teopanzolco, Jacarandas, 62420 Cuernavaca, MOR, Mexico",
        "latitud": 18.9222615,
        "longitud": -99.2209856,
        "estado": "Morelos",
        "municipio": "Cuernavaca",
        "localidad": "Cuernavaca",
        "codigo_postal": "62420"
    }
}

21. Obtener dirección completa a partir de un código postal

Este endpoint permite consultar el estado, municipio y colonias correspondientes a un código postal específico. Es útil para autocompletar formularios o validar información de direcciones en procesos administrativos.

Endpoint

GET https://locatomx.kharmasolutions.com/mx/info/ubicacion/por-codigo-postal?codigo_postal={codigo_postal}

Campo	Descripción	Requerido
`codigo_postal`	Código postal del cual se desea obtener la ubicación completa.	Sí

Ejemplo en cURL

curl --location 'https://locatomx.kharmasolutions.com/mx/info/ubicacion/por-codigo-postal?codigo_postal=62420' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: 4249cba5-****-****-****-************'

Ejemplo Respuesta

{
    "success": true,
    "message": "Ubicación encontrada para el código postal 62420.",
    "data": {
        "codigo_postal": "62420",
        "estado": {
            "uuid": "7898bba7-0db2-4a5e-bc20-2a5a48f79fd6",
            "nombre": "MORELOS"
        },
        "municipio": {
            "uuid": "7c1c11cc-2435-4ea3-aa89-6db5bbbf77f6",
            "nombre": "CUERNAVACA"
        },
        "colonias": [
            {
                "uuid": "3d41acea-ca92-40fe-94c2-89b03da6725a",
                "nombre": "JACARANDAS",
                "tipo_comunidad": {
                    "uuid": "38588e80-6ba4-4479-bec7-03452b12aa90",
                    "nombre": "COLONIA"
                }
            },
            {
                "uuid": "78e089ee-e5ad-4a39-943b-c7fc66eb4640",
                "nombre": "QUINTAS MARTHA",
                "tipo_comunidad": {
                    "uuid": "38588e80-6ba4-4479-bec7-03452b12aa90",
                    "nombre": "COLONIA"
                }
            }
        ]
    }
}

Respuestas de error comunes

Esta sección documenta los posibles errores que la API puede retornar. Es útil para que los desarrolladores manejen correctamente las excepciones del lado del cliente.

Errores HTTP

Listado de errores

Código	Descripción	Detalle
`404`	Ruta no encontrada	La ruta solicitada no existe o está mal escrita.
`405`	Método no permitido	El método HTTP utilizado no está permitido en esta ruta.
`404`	Recurso no encontrado	El recurso solicitado (modelo) no existe en la base de datos.
`500`	Error interno del servidor	Se generó una excepción inesperada durante la ejecución.

🧪 Ejemplos de respuestas JSON

🔍 Error 404 - Ruta no encontrada

Ocurre cuando el cliente solicita una ruta que no existe en el sistema.

{
    "success": false,
    "message": "Ruta no encontrada.",
    "code": 404
}

🔄 Error 405 - Método HTTP no permitido

Se produce cuando se utiliza un método HTTP (como POST, PUT, DELETE) no habilitado para la ruta especificada.

{
    "success": false,
    "message": "Método HTTP no permitido.",
    "code": 405
}

📭 Error 404 - Recurso no encontrado

El modelo solicitado no fue localizado en la base de datos. Probablemente el identificador no existe.

{
    "success": false,
    "message": "Recurso no encontrado.",
    "code": 404
}

💥 Error 500 - Interno del servidor

Ocurre cuando algo inesperado falla dentro del servidor. Generalmente es una excepción no controlada.

{
    "success": false,
    "message": "Error interno del servidor.",
    "error": "Descripción del error.",
    "code": 500
}