REST API · JSON

Documentación de Koordex · ValidaDirecciones API

Koordex te permite validar, normalizar y geolocalizar direcciones en México y Latinoamérica. Todas las respuestas son en JSON y se accede mediante Authorization: Bearer {API_KEY}.

🔑 Autenticación por API Key 📍 Datos: calle, número, colonia, CP, municipio, estado, país, lat, lng ⚡ Pensada para e-commerce, logística y CRMs

Resumen rápido

POST https://koordex.software/api/index.php

Headers requeridos

Content-Type: application/json
Authorization: Bearer TU_API_KEY

Body (JSON)

{
  "address": "Providencia 1540, Tlacoquemécatl, Benito Juárez, Ciudad de México",
  "country": "MX"
}

Respuesta (ejemplo)

{
  "success": true,
  "normalized": {
    "calle": "Providencia",
    "numero": "1540",
    "colonia": "Tlacoquemécatl del Valle",
    "cp": "03200",
    "municipio": "Ciudad de México",
    "estado": "Ciudad de México",
    "pais": "México"
  },
  "location": {
    "lat": 19.3754154,
    "lng": -99.1725513
  },
  "quality": {
    "precision": "ROOFTOP",
    "source": "google"
  },
  "meta": {
    "cached": false
  }
}

Autenticación

La API utiliza autenticación mediante API Key en el encabezado Authorization usando el esquema Bearer.

Puedes obtener tu API Key creando una cuenta en el panel de clientes y copiándola desde la sección “Tu API Key”.

Formato del header Authorization: Bearer TU_API_KEY_AQUI

Límites por plan BÁSICO · 2,000 requests/mes PRO · 15,000 requests/mes PREMIUM · casi ilimitado

Endpoint y parámetros

Endpoint principal:

POST https://koordex.software/api/index.php

Este endpoint recibe una dirección libre en el campo address y un país opcional (country, por defecto MX) y devuelve la dirección normalizada y geolocalizada.

Parámetros (body JSON)

Campo	Tipo	Obligatorio	Descripción
`address`	string	Sí	Dirección completa tal como la captura el usuario.
`country`	string	No (por defecto `MX`)	Código de país ISO-3166 (ej. `MX`).

Ejemplos de uso

Ejemplo con curl

curl -X POST "https://koordex.software/api/index.php" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -d '{
    "address": "Providencia 1540, Tlacoquemécatl, Benito Juárez, Ciudad de México",
    "country": "MX"
  }'

Ejemplo en PHP (cURL)

$apiKey = 'TU_API_KEY';
$url = 'https://koordex.software/api/index.php';

$data = [
  'address' => 'Providencia 1540, Tlacoquemécatl, Benito Juárez, Ciudad de México',
  'country' => 'MX'
];

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
  ],
  CURLOPT_POSTFIELDS     => json_encode($data),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Ejemplo en JavaScript (fetch)

const apiKey = 'TU_API_KEY';

fetch('https://koordex.software/api/index.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + apiKey
  },
  body: JSON.stringify({
    address: 'Av. Insurgentes Sur 3000, Ciudad de México',
    country: 'MX'
  })
})
.then(res => res.json())
.then(data => {
  console.log('Respuesta API:', data);
})
.catch(err => console.error(err));

Ejemplo en Python (requests)

import requests

api_key = 'TU_API_KEY'
url = 'https://koordex.software/api/index.php'

payload = {
  "address": "Av. Insurgentes Sur 3000, Ciudad de México",
  "country": "MX"
}

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

resp = requests.post(url, json=payload, headers=headers)
print(resp.status_code)
print(resp.json())

Códigos de respuesta y errores

La API utiliza códigos HTTP estándar. Además, algunas respuestas incluyen un campo error o información adicional en quality.

2xx · Éxito 4xx · Error del cliente 5xx · Error del servidor

Código	Significado	Detalle
200	OK	Dirección validada correctamente. Devuelve `success: true` y los datos normalizados.
400	Bad Request	Falta el campo `address` o el JSON está mal formado.
401	Unauthorized	Falta o es inválido el header `Authorization: Bearer TU_API_KEY`.
422	Unprocessable Entity	No se pudo validar la dirección (por ejemplo, Google no encontró resultados).
429	Too Many Requests	Has alcanzado tu límite mensual de peticiones según tu plan.
500	Internal Server Error	Error interno del servidor (problema de conexión o error inesperado).