Documentación de la API de Mapora

Empieza con una petición

Base URL: https://maps-api.nexode.app. Crea una clave en API keys con los permisos que vayas a usar. Envía X-API-Key o Authorization: Bearer TU_API_KEY; nunca la clave en la URL.

curl "https://maps-api.nexode.app/v1/search?q=Miraflores&countrycodes=PE&limit=5" \
  -H "X-API-Key: TU_API_KEY"

No necesitas mostrar un mapa. Todos los endpoints de consulta devuelven JSON. Puedes guardar los datos desde tu backend, mostrar solo un buscador o añadir un mapa cuando tu flujo lo requiera.

Claves de servidor y de navegador

mp_live_ es una clave privada para tu backend. mp_pub_ es una clave visible para navegador y permite únicamente search, reverse y nearby, según los permisos elegidos. Registra de 1 a 10 orígenes HTTPS exactos, sin rutas ni comodines; HTTP se admite solo para localhost y loopback en desarrollo.

La restricción de Origin limita el uso desde otros navegadores; no autentica servidores ni convierte la clave en un secreto. Para rutas, matrices, cobertura, lotes, resolución de enlaces y creación de mapas, llama desde tu backend con una clave privada. No incluyas secretos en React ni en un repositorio público.

Permisos disponibles: search, reverse, resolve, maps, nearby, batch, coverage y routing. Las claves existentes conservan sus permisos; crea una nueva si necesitas otras operaciones. La clave completa se muestra solo al crearla y puedes revocarla desde el panel.

Referencia de endpoints

Abre una operación para consultar sus parámetros, el formato de respuesta y un ejemplo cURL. Los cuerpos POST usan Content-Type: application/json.

curl "https://maps-api.nexode.app/v1/search?q=Miraflores&countrycodes=PE&limit=5" \
  -H "X-API-Key: TU_API_KEY"

curl "https://maps-api.nexode.app/v1/autocomplete?q=Avenida+Larco&countrycodes=PE&limit=5" \
  -H "X-API-Key: TU_API_KEY"

curl "https://maps-api.nexode.app/v1/geocode?street=Avenida+Jose+Larco&city=Lima&countrycodes=PE&limit=5" \
  -H "X-API-Key: TU_API_KEY"

curl "https://maps-api.nexode.app/v1/reverse?lat=-12.1199&lng=-77.029" \
  -H "X-API-Key: TU_API_KEY"

curl "https://maps-api.nexode.app/v1/resolve" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.google.com/maps?q=-12.0453,-77.0309","includeAddress":true}'

curl "https://maps-api.nexode.app/v1/nearby?lat=-12.1199&lng=-77.029&category=pharmacy&radius=1000&limit=8" \
  -H "X-API-Key: TU_API_KEY"

curl "https://maps-api.nexode.app/v1/batch" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"pedido-1","query":"Miraflores Lima","countrycodes":"PE"},{"id":"pedido-2","query":"Chapinero Bogota","countrycodes":"CO"}]}'

curl "https://maps-api.nexode.app/v1/coverage" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"point":{"latitude":-12.1199,"longitude":-77.029},"zones":[{"name":"Miraflores","geometry":{"type":"Polygon","coordinates":[[[-77.04,-12.13],[-77.02,-12.13],[-77.02,-12.11],[-77.04,-12.11],[-77.04,-12.13]]]},"feeCents":500,"currency":"PEN"}]}'

curl "https://maps-api.nexode.app/v1/coverage/check" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"point":{"latitude":-12.1199,"longitude":-77.029},"zoneIds":["REEMPLAZA_POR_ID_DE_TU_ZONA"]}'

curl "https://maps-api.nexode.app/v1/routes" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations":[{"latitude":-12.1199,"longitude":-77.029},{"latitude":-12.122,"longitude":-77.034}],"profile":"driving"}'

curl "https://maps-api.nexode.app/v1/matrix" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sources":[{"latitude":-12.1199,"longitude":-77.029},{"latitude":-12.122,"longitude":-77.034}],"targets":[{"latitude":-12.1199,"longitude":-77.029},{"latitude":-12.122,"longitude":-77.034}],"profile":"driving"}'

curl "https://maps-api.nexode.app/v1/maps" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Mi ubicación","center":{"latitude":-12.1199,"longitude":-77.029},"zoom":14,"theme":"light","accent":"#174c43","markers":[{"latitude":-12.1199,"longitude":-77.029,"label":"Punto de entrega"}],"expiresIn":604800}'

Busca por país, ciudad o área

countrycodes=PE restringe a Perú; countrycodes=PE,CO permite Perú y Colombia. Omite el parámetro para búsqueda mundial.

Si tienes la dirección separada en campos, usa /v1/geocode con city, street, housenumber u otros componentes. city es un componente de la consulta estructurada, no un límite administrativo garantizado.

GET /v1/geocode?street=Avenida+Larco&city=Lima&countrycodes=PE

GET /v1/autocomplete?q=Avenida+Larco&countrycodes=PE&lat=-12.12&lng=-77.03

GET /v1/search?q=Avenida+Larco&countrycodes=PE&bbox=-77.10,-12.20,-76.90,-12.00

La búsqueda libre y el autocompletado también admiten city, district y state. Se comparan nombres administrativos normalizados; usa país y ciudad juntos para distinguir lugares homónimos. lat/lng prioriza cercanía y bbox acota un rectángulo en el orden minLng,minLat,maxLng,maxLat. Confirma el resultado antes de guardarlo.

GET /v1/search?q=Avenida+Larco+289&countrycodes=PE&city=Lima
GET /v1/autocomplete?q=Avenida+Larco&countrycodes=PE&city=Lima&district=Miraflores

Índice propio de calles de Perú

La búsqueda combina el índice mundial con un índice local de más de 190000 registros de vías de Perú y referencias de planos municipales de Trujillo. Tolera acentos y abreviaturas de tipo de vía; si no encuentra el número, puede devolver la calle con quality.precision:street.

Una referencia de calle devuelve match.coordinateType:street_reference, match.houseNumberMatched:false y, cuando corresponde, match.requestedHouseNumber. Su punto es una referencia de la vía, no la ubicación de la casa. Los puntos municipales provienen de las etiquetas georreferenciadas del plano de trabajo; confirma y ajusta el pin para una entrega. sourceURL y sourceDate dentro de match identifican la fuente y su fecha.

La cobertura depende de los datos disponibles; no garantiza todas las calles ni numeraciones de Perú. El índice derivado descargable contiene nombres y referencias de calles, con atribución de OpenStreetMap, INEI y la municipalidad según la fuente. La base de OpenStreetMap se distribuye bajo ODbL 1.0.

Guarda el nombre y el punto elegido

Una ubicación puede incluir placeName, address, streetAddress, latitude, longitude, calle, número, distrito, ciudad, región, país y código postal. Conserva también source, attribution y el enlace original cuando tu flujo lo necesite. No todos los campos están disponibles en todos los lugares.

En una consulta inversa, latitude/longitude son tu pin. matchedLatitude/matchedLongitude son la referencia cercana: no reemplaces automáticamente el pin con esa coincidencia. Al resolver un enlace, conserva también addressStatus y resolved_url.

quality.precision describe el tipo de dato disponible, quality.missingFields señala componentes faltantes y quality.verified es false. No es una certificación del domicilio ni una garantía de entrega. Muestra la atribución de OpenStreetMap junto a los resultados.

Rutas por calles en América

La búsqueda y la cartografía cubren el mundo. El motor de rutas y matrices cubre América: Sudamérica, Centroamérica, Caribe, México, Estados Unidos y Canadá, según las vías disponibles para el perfil. Europa queda fuera de la cobertura de rutas actual.

Envía las paradas en orden a POST /v1/routes. La respuesta incluye geometría GeoJSON, distancia en metros, duración estimada en segundos e instrucciones en español. locations conserva tus coordenadas; snappedLocations identifica los puntos sobre la vía. Los índices beginShapeIndex y endShapeIndex de cada instrucción apuntan a la geometría completa; legIndex identifica el tramo.

Para comparar destinos usa POST /v1/matrix: cada fila corresponde a un origen y cada columna a un destino. null significa que no hay conexión para ese par. La cobertura de un país no implica que exista un trayecto entre países o islas.

No incluye tráfico en tiempo real, transporte público, elevación ni planificación por hora de salida. Un trayecto fuera del índice o inaccesible devuelve 422 route_not_found, sin inventar una línea recta. Puedes consumir toda la respuesta como JSON, sin mostrar un mapa.

Mapas de tu marca, cuando los necesites

POST /v1/maps devuelve url, embedHtml, expiresAt y la especificación del mapa. Abre el enlace o inserta el iframe. Tu aplicación puede crear el mapa directamente mediante la API.

Admite estilos light, dark y grayscale, color accent, hasta 200 marcadores agrupados automáticamente, 10 polígonos y una ruta LineString de hasta 10000 puntos. GeoJSON usa [longitud, latitud]; los objetos de ubicación usan { latitude, longitude }.

Mostrar una ruta calculada

Desde tu backend, conserva la geometría de rutas y pásala al campo route del mapa. Son dos operaciones admitidas y consumen dos peticiones. Una geometría de más de 10000 puntos debe simplificarse antes de enviarla al visor.

// Backend: API_KEY es privada; no la incluyas en el frontend.
async function postMapora(path, body) {
  const response = await fetch('https://maps-api.nexode.app' + path, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  const data = await response.json();
  if (!response.ok) throw new Error(data.error);
  return data;
}
const points = [
  { latitude: -12.1199, longitude: -77.029 },
  { latitude: -12.122, longitude: -77.034 }
];
const route = await postMapora('/v1/routes', {
  locations: points, profile: 'driving'
});
const map = await postMapora('/v1/maps', {
  title: 'Mi recorrido', center: points[0], markers: points,
  route: route.geometry, theme: 'light', accent: '#174c43'
});
// Devuelve map.url o map.embedHtml a tu aplicación.

Quien recibe el enlace puede ver ese mapa, sin conocer tu API key. El token solo autoriza la lectura de esa vista y su cartografía. El enlace caduca en 7 días por defecto, configurable de 60 segundos a 30 días. La caducidad, revocar la clave creadora o suspender la cuenta impide nuevas lecturas; no borra una vista ya cargada en otro navegador.

Crear el mapa consume una petición. Abrirlo, moverlo, hacer zoom y cargar mosaicos no añade peticiones geográficas. La cartografía vectorial mundial usa datos de OpenStreetMap y Protomaps. No incluye imágenes satelitales, descarga masiva ni uso sin conexión.

React y JavaScript

Descargar React 2.1.0 · Descargar cliente JavaScript. El paquete React se instala desde el archivo; no está publicado en el registro público de npm. Requiere React 19 y un bundler compatible; el mapa necesita WebGL.

npm install ./mapora-react-2.1.0.tgz

Solo buscador, sin mapa

import { MaporaAddressSearch } from '@mapora/react';
import '@mapora/react/style.css';

<MaporaAddressSearch
  apiKey="mp_pub_TU_CLAVE_DE_NAVEGADOR"
  country="PE"
  city="Lima"
  district="Miraflores"
  bias={{ latitude: -12.12, longitude: -77.03 }}
  onQueryChange={() => invalidarSeleccionAnterior()}
  onSelect={(location) => guardarDireccion(location)}
/>

country limita el país; city, district y state filtran por contexto administrativo, y bias prioriza una zona. Todos son opcionales. El componente gestiona sugerencias, espera de 350 ms desde tres caracteres, cancelación y navegación por teclado. Invalida la selección anterior al editar el texto antes de enviar una ruta o comprobar cobertura. Si seleccionas una referencia de calle, el número sigue sin confirmar.

Buscador con pin ajustable

import { MaporaLocationPicker } from '@mapora/react';
import '@mapora/react/style.css';

<MaporaLocationPicker
  apiKey="mp_pub_TU_CLAVE_DE_NAVEGADOR"
  baseURL="https://maps-api.nexode.app"
  country="PE"
  theme="light"
  accent="#174c43"
  initialCenter={{ latitude: -12.12, longitude: -77.03 }}
  onSelect={(location) => guardarDireccion(location)}
/>

Usa una clave de navegador con search y reverse y registra el origen exacto de tu web. Omite country para búsqueda mundial. Puedes cambiar theme, accent, className y style. onSelect puede recibir primero el pin y luego su referencia de dirección: conserva siempre las coordenadas elegidas. Incluye declaraciones TypeScript y un worker empaquetado para el mapa.

Cliente JavaScript para los endpoints

// Guarda el archivo descargado en tu proyecto.
import { Mapora } from './mapora-client.js';
const maps = new Mapora({ apiKey: API_KEY });
const results = await maps.geocode({
  street: 'Avenida Larco', city: 'Lima', countrycodes: 'PE'
});

El cliente expone search, autocomplete, geocode, reverse, nearby, resolve, batch, coverage, checkCoverage, routes, matrix y map. Usa claves privadas solo en servidor; en navegador se aplican las restricciones de mp_pub_. Los errores HTTP incluyen status, code y retryAfter.

Consumo, cuotas y errores

Una petición HTTP autenticada admitida equivale a una unidad, también desde caché o si devuelve un error de validación o proveedor. Un lote de hasta 10 direcciones cuenta como una petición; una matriz de hasta 100 pares también. Cada consulta de autocompletado o inversa cuenta por separado. Cancelar un fetch no garantiza que el servidor no lo haya admitido.

Los rechazos por clave, permiso, origen o cuota no consumen unidades. Las visualizaciones de mapas, cartografía, descargas del SDK y consultas de estado no añaden peticiones geográficas. Scale elimina la cuota mensual, pero conserva el límite por minuto y las protecciones del servicio. Consulta los límites vigentes en Plan y facturación; no hay cobros automáticos por excedentes.

Las cabeceras X-Quota-Limit, X-Quota-Remaining y X-Quota-Reset muestran la cuota. Respeta Retry-After al recibir 429. Algunas respuestas incluyen cached, tookMs y X-Cache; la caché no cambia el consumo.

Los errores JSON tienen { "code": "…", "error": "…" }. Usa code para decidir el comportamiento; el mensaje es legible para personas. No sustituyas una dirección no disponible por una dirección verificada.

Estado del servicio

GET /health comprueba el proceso. GET /status devuelve el estado de búsqueda, cartografía, rutas y base de datos, con caché de hasta un minuto y cobertura actual. No requieren clave ni son un historial de disponibilidad. Consulta también el estado visual de los motores.

Del panel a tu integración

API keys

Crea claves por proyecto, elige permisos y registra orígenes para navegador. Guarda la clave completa al crearla; revócala cuando deje de usarse. Hasta diez claves activas por cuenta.

Explorar

Busca por país, confirma una dirección o ajusta un pin. Consulta lugares cercanos y prueba rutas en auto, bicicleta o a pie con tu propia clave.

Importar direcciones

Procesa un CSV de hasta 1000 filas y 1 MB, en lotes de 10. Usa la plantilla del panel, revisa el resultado por fila y descarga los resultados. El archivo no se guarda; cada lote admitido consume una petición.

Consumo y facturación

Consulta peticiones por operación, estado y latencia. Los registros de consumo no guardan direcciones, coordenadas ni cuerpos de las consultas. Gestiona plan, facturas y suscripción de Stripe desde Plan y facturación.

Mi perfil

Gestiona tu cuenta y cierra sesión. Las herramientas del panel usan tu sesión; la API geográfica usa API keys. No son credenciales intercambiables.

La documentación del sitio y del panel comparte esta misma referencia. La especificación OpenAPI 3.1 contiene los esquemas de petición y respuesta para generar clientes.