Documentación

Todo lo que necesitas para integrar Navega.do en tu aplicación.

Quick Start

Integra un mapa de República Dominicana en tu web en 2 minutos.

1. Obtén tu API Key

Regístrate en navega.do y crea una API key desde el Dashboard.

2. Añade el mapa a tu página

<!-- Navega.do SDK — MapLibre GL JS v4.7.1 (self-hosted) -->
<link rel="stylesheet" href="https://api.navega.do/vendor/maplibre/maplibre-gl.css">
<script src="https://api.navega.do/vendor/maplibre/maplibre-gl.js"></script>

<!-- Container del mapa -->
<div id="map" style="width: 100%; height: 400px;"></div>

<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://api.navega.do/styles/dark?key=TU_API_KEY',
    center: [-69.93, 18.48], // Santo Domingo
    zoom: 12
  });
</script>

SDK self-hosted: MapLibre GL JS v4.7.1 se sirve desde nuestros servidores con cache inmutable de 1 año. No necesitas depender de CDN externos.

Autenticación

Todas las requests a la API requieren una API key válida. Puedes enviarla de dos formas:

Query Parameter (recomendado para tiles)

GET /tiles/dominican-republic/12/1234/5678?key=nd_tu_api_key

Header (recomendado para API calls)

X-API-Key: nd_tu_api_key

Bearer Token (para endpoints del dashboard)

Authorization: Bearer tu_jwt_token

Tiles API

GET /tiles/{source}/{z}/{x}/{y}

Obtiene un tile vectorial en formato PBF (Protocol Buffers).

Parámetro	Tipo	Descripción
`source`	string	Nombre del dataset. Ej: `dominican-republic`
`z`	int	Nivel de zoom (0-14)
`x`	int	Coordenada X del tile
`y`	int	Coordenada Y del tile
`key`	string	Tu API key

Ejemplo con curl

curl "https://api.navega.do/tiles/dominican-republic/12/1234/5678?key=nd_abc123"

Estilos

GET /styles/{style_name}?key=API_KEY

Devuelve un JSON de estilo compatible con MapLibre GL, con las URLs de tiles ya configuradas con tu API key.

Estilo	Descripción	Ideal para
`dark`	Fondo oscuro con acentos en verde — 37 capas	Apps nocturnas, dashboards
`light`	Fondo claro, estilo clásico — 36 capas	Webs corporativas, inmobiliarias
`streets`	Colores vivos, orientado a navegación — 37 capas	Apps de delivery, transporte

Características de los estilos

Edificios 3D — extrusión por altura en zooms 14+
Road casings — bordes en vías para mejor legibilidad
Aerovías — pistas de aterrizaje y aeródromos etiquetados
Picos montañosos — iconos de elevación con nombres
Flechas de sentido único — indicadores en calles one-way
Labels localizados — español preferido (name:es), fallback a name
Popups interactivos — click en POIs, parques, lugares, aeródromos y montañas

Ejemplo

curl "https://api.navega.do/styles/dark?key=nd_abc123"

// Retorna un Style JSON completo con tile URLs inyectadas:
{
  "version": 8,
  "name": "Navega Dark",
  "sources": { ... },
  "layers": [ ... // 37 capas ]
}

Forward Geocoding

Convierte texto (direcciones, nombres de lugares) en coordenadas. Usa búsqueda fuzzy con pg_trgm para tolerar errores de escritura.

GET /api/geocoding/forward?q={texto}&key=API_KEY

Busca lugares, provincias, municipios, barrios y calles de República Dominicana.

Parámetro	Tipo	Descripción
`q`	string	Requerido. Texto a geocodificar (mín. 2, máx. 200 caracteres)
`limit`	int	Máx. resultados (1-20, default: 5)
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/geocoding/forward?q=punta+cana&key=nd_abc123"

// Respuesta
{
  "query": "punta cana",
  "results": [
    {
      "id": 1234,
      "name": "Punta Cana",
      "display_name": "Punta Cana, La Altagracia, República Dominicana",
      "place_type": "LOCALITY",
      "latitude": 18.5601,
      "longitude": -68.3725,
      "address": {
        "province": "La Altagracia",
        "country": "DO"
      },
      "importance": 0.6
    }
  ]
}

Reverse Geocoding

Convierte coordenadas (latitud, longitud) en la dirección o lugar más cercano.

GET /api/geocoding/reverse?lat={lat}&lng={lng}&key=API_KEY

Retorna los lugares más cercanos a las coordenadas dadas.

Parámetro	Tipo	Descripción
`lat`	float	Requerido. Latitud (-90 a 90)
`lng`	float	Requerido. Longitud (-180 a 180)
`limit`	int	Resultados a devolver (1-5, default: 1)
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/geocoding/reverse?lat=18.4861&lng=-69.9312&key=nd_abc123"

// Respuesta
{
  "latitude": 18.4861,
  "longitude": -69.9312,
  "results": [
    {
      "name": "Zona Colonial",
      "display_name": "Zona Colonial, Santo Domingo, República Dominicana",
      "place_type": "NEIGHBORHOOD",
      "distance_km": 0.15,
      ...
    }
  ]
}

Directions — Ruta

Calcula rutas entre dos puntos usando OSRM. Soporta perfiles de conducción, caminata y bicicleta con instrucciones paso a paso.

GET /api/directions/route?origin={lat,lng}&destination={lat,lng}&key=API_KEY

Retorna geometría GeoJSON, distancia, duración e instrucciones de la ruta.

Parámetro	Tipo	Descripción
`origin`	string	Requerido. `lat,lng` del punto de origen
`destination`	string	Requerido. `lat,lng` del destino
`profile`	string	`driving` (default), `walking`, `cycling`
`alternatives`	bool	Incluir rutas alternativas (default: false)
`steps`	bool	Instrucciones turn-by-turn (default: true)
`geometries`	string	`geojson` (default) o `polyline`
`overview`	string	`full` (default), `simplified`, `false`
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/directions/route?origin=18.4861,-69.9312&destination=18.5601,-68.3725&profile=driving&key=nd_abc123"

// Respuesta
{
  "origin": { "lat": 18.4861, "lng": -69.9312 },
  "destination": { "lat": 18.5601, "lng": -68.3725 },
  "profile": "driving",
  "routes": [
    {
      "distance_m": 198543,
      "duration_s": 8420,
      "geometry": { "type": "LineString", "coordinates": [...] },
      "steps": [
        {
          "instruction": "Autopista Las Americas",
          "distance_m": 45200,
          "duration_s": 1800,
          "maneuver": { "type": "turn", "modifier": "right" }
        }
      ]
    }
  ]
}

Directions — Matriz de Distancias

Calcula distancias y tiempos entre múltiples orígenes y destinos en una sola request.

GET /api/directions/matrix?origins={coords}&key=API_KEY

Retorna una matriz NxM de distancias (metros) y duraciones (segundos).

Parámetro	Tipo	Descripción
`origins`	string	Requerido. Pares `lat,lng` separados por `;`
`destinations`	string	Pares `lat,lng` separados por `;` (si se omite, usa origins)
`profile`	string	`driving` (default), `walking`, `cycling`
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/directions/matrix?origins=18.48,-69.93;18.50,-69.90&destinations=18.56,-68.37&key=nd_abc123"

Búsqueda Unificada

Un solo endpoint que busca simultáneamente en POIs, lugares geocodificados y categorías. Los resultados se rankean por relevancia (trigram similarity) y proximidad geográfica.

GET /api/search?q={texto}&key=API_KEY

Busca en todas las fuentes de datos y devuelve resultados combinados y rankeados.

Parámetro	Tipo	Descripción
`q`	string	Requerido. Texto a buscar (mín. 2, máx. 200 caracteres)
`lat`	float	Latitud para boost por proximidad
`lng`	float	Longitud para boost por proximidad
`types`	string	Filtrar por tipo: `poi`, `place`, `category` (comma-separated)
`limit`	int	Máx. resultados (1-50, default: 10)
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/search?q=farmacia&lat=18.48&lng=-69.93&types=poi&key=nd_abc123"

Proximity boost: Si envías lat y lng, los resultados cercanos a esas coordenadas se priorizan automáticamente.

Autocomplete

Sugerencias rápidas mientras el usuario teclea. Ideal para barras de búsqueda — retorna resultados en <50ms.

GET /api/autocomplete?q={texto}&key=API_KEY

Retorna sugerencias de autocompletado para el texto parcial.

Parámetro	Tipo	Descripción
`q`	string	Requerido. Texto parcial (mín. 1 caracter)
`lat`	float	Latitud para boost por proximidad
`lng`	float	Longitud para boost por proximidad
`limit`	int	Máx. sugerencias (1-10, default: 5)
`key`	string	Requerido. Tu API key

Ejemplo

curl "https://api.navega.do/api/autocomplete?q=farm&lat=18.48&lng=-69.93&key=nd_abc123"

// Respuesta
{
  "query": "farm",
  "suggestions": [
    { "text": "Farmacia Carol", "type": "poi", "category": "pharmacy" },
    { "text": "Farmacia Los Hidalgos", "type": "poi", "category": "pharmacy" },
    { "text": "Farmacias", "type": "category" }
  ]
}

Integración en un input

const input = document.getElementById('search-input');
let controller;

input.addEventListener('input', async (e) => {
  if (controller) controller.abort();
  controller = new AbortController();
  const res = await fetch(
    `/api/autocomplete?q=${encodeURIComponent(e.target.value)}&key=${API_KEY}`,
    { signal: controller.signal }
  );
  const { suggestions } = await res.json();
  // Render suggestions...
});

Places / POIs API

Busca comercios, restaurantes, farmacias, tiendas y miles de puntos de interés en República Dominicana. Datos de Overture Maps Foundation y OpenStreetMap.

Buscar por texto

GET /api/pois/search?q={query}&key=API_KEY

Busca POIs por nombre, marca o subcategoría.

Parámetro	Tipo	Descripción
`q`	string	Requerido. Texto a buscar (mín. 2 caracteres)
`category`	string	Filtrar por categoría: `restaurant`, `pharmacy`, `bank`, etc.
`city`	string	Filtrar por ciudad
`limit`	int	Máx. resultados (1-100, default: 20)
`offset`	int	Paginación

Ejemplo

curl "https://api.navega.do/api/pois/search?q=pizza&city=santo+domingo&key=nd_abc123"

// Respuesta
{
  "total": 47,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "id": "osm:node:123456",
      "name": "Pizza Hut Naco",
      "category": "restaurant",
      "subcategory": "pizza",
      "latitude": 18.4752,
      "longitude": -69.9284,
      "address": "Av. Tiradentes #45, Naco",
      "city": "Santo Domingo",
      "phone": "+1-809-555-1234",
      "source": "osm",
      "confidence": 0.9
    }
  ]
}

Buscar por cercanía

GET /api/pois/nearby?lat={lat}&lng={lng}&radius={metros}&key=API_KEY

Busca POIs dentro de un radio desde un punto. Incluye distance_m en cada resultado.

Parámetro	Tipo	Descripción
`lat`	float	Requerido. Latitud del centro
`lng`	float	Requerido. Longitud del centro
`radius`	int	Radio en metros (100-50,000, default: 1000)
`category`	string	Filtrar por categoría
`limit`	int	Máx. resultados (1-100, default: 20)

Ejemplo nearby

curl "https://api.navega.do/api/pois/nearby?lat=18.4861&lng=-69.9312&radius=2000&category=pharmacy&key=nd_abc123"

Categorías

GET /api/pois/categories

Lista todas las categorías de POI disponibles (no requiere API key).

Detalle de POI

GET /api/pois/{poi_id}?key=API_KEY

Obtiene info completa de un POI: horarios, tags, Facebook, etc.

Categorías disponibles: restaurant, cafe, fast_food, bar, pharmacy, hospital, clinic, school, bank, fuel, supermarket, convenience, hotel, beauty, bakery, park, pizza, seafood y más.

Tráfico en Vivo

Datos de tráfico en tiempo real para toda República Dominicana. Se actualiza cada 2 minutos con ~400-500 segmentos de vías.

GET /api/traffic/live?key=API_KEY

Retorna un GeoJSON FeatureCollection con líneas de congestión vial. Cada feature es un segmento de vía con nivel de tráfico, velocidad y metadata.

Parámetro	Tipo	Descripción
`key`	string	Requerido. Tu API key

Propiedades de cada Feature

Propiedad	Tipo	Descripción
`level`	int	Nivel de congestión: `0` libre, `1` leve, `2` moderado, `3` grave, `4` parado, `5` bloqueado
`speed`	float	Velocidad actual en km/h
`street`	string	Nombre de la vía
`city`	string	Ciudad o localidad
`delay`	int	Retraso en segundos vs flujo libre
`length`	int	Longitud del segmento en metros
`roadType`	int	Tipo de vía (1=autopista, 2=primaria, etc.)

Ejemplo

curl "https://api.navega.do/api/traffic/live?key=nd_abc123"

// Respuesta — GeoJSON FeatureCollection (~230 KB, ~450 features)
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [[-69.93, 18.48], [-69.92, 18.49], ...]
      },
      "properties": {
        "level": 3,
        "speed": 14.5,
        "street": "Av. 27 de Febrero",
        "city": "Santo Domingo",
        "delay": 245,
        "length": 1830,
        "roadType": 2
      }
    }
  ]
}

Uso con MapLibre GL JS

// Añadir capa de tráfico al mapa
const res = await fetch(`/api/traffic/live?key=${API_KEY}`);
const geojson = await res.json();

map.addSource('traffic', { type: 'geojson', data: geojson });

// Capa para tráfico grave (level 3)
map.addLayer({
  id: 'traffic-heavy',
  type: 'line',
  source: 'traffic',
  filter: ['==', ['get', 'level'], 3],
  paint: {
    'line-color': '#E70704',
    'line-width': 4,
    'line-opacity': 0.85
  }
});

Colores sugeridos por nivel

Nivel	Label	Color
0	Libre	#2EAB30
1	Leve	#F1BF40
2	Moderado	#F18237
3	Grave	#E70704
4	Parado	#9E1006
5	Bloqueado	#6E0704

Cache: La respuesta incluye Cache-Control: max-age=120. Recomendamos refrescar cada 2 minutos para datos frescos sin sobrecargar la API.

Segmentos y Congestión

Endpoints adicionales para consultar datos de tráfico almacenados por área geográfica.

Segmentos de tráfico

GET /api/traffic/segments?lat={lat}&lng={lng}&radius={metros}&key=API_KEY

Obtiene segmentos de vía con datos de velocidad y congestión en un área.

Parámetro	Tipo	Descripción
`lat`, `lng`	float	Centro del área
`radius`	int	Radio en metros (100-20,000)
`min_congestion`	int	Nivel mínimo: 0=libre, 1=leve, 2=moderado, 3=grave, 4=parado, 5=bloqueado
`limit`	int	Máx. resultados (1-200, default: 50)

Resumen de congestión

GET /api/traffic/congestion?lat={lat}&lng={lng}&radius={metros}&key=API_KEY

Resumen agregado: cantidad de segmentos y velocidad promedio por nivel de congestión.

API Keys

GET /api/keys/

Lista todas tus API keys.

POST /api/keys/

Crea una nueva API key.

{
  "name": "Mi App de Delivery",
  "allowed_origins": "https://miapp.com"
}

DELETE /api/keys/{key_id}

Revoca una API key. Las apps que la usen recibirán error 403.

Uso & Límites

GET /api/usage/current

Uso del mes actual. Requiere JWT Bearer token.

{
  "month": "2026-04",
  "total_requests": 4523,
  "limit": 100000,
  "plan": "growth"
}

GET /api/usage/history

Historial de uso de los últimos 12 meses. Requiere JWT Bearer token.

// Retorna array de objetos UsageResponse
[
  { "month": "2026-04", "total_requests": 4523, "limit": 100000, "plan": "growth" },
  { "month": "2026-03", "total_requests": 12080, "limit": 100000, "plan": "growth" },
  ...
]

Rate Limits

Plan	Requests/Mes	API Keys	APIs incluidas	Precio
Starter	5,000	1	Tiles + Estilos	$0
Growth	100,000	5	Tiles + Geocoding + Routing	$49/mes
Business	400,000	Ilimitadas	Todo + Places + Traffic + SLA 99.9%	$199/mes
Enterprise	>1,000,000	Ilimitadas	Todo + On-premise	Personalizado
💡 Requests adicionales: $0.50 / 1,000 — el servicio nunca se interrumpe.

Exceder el límite: Los requests extra se cobran a $0.50/1,000. Tu servicio nunca se interrumpe.

MapLibre GL JS

SDK self-hosted — MapLibre GL JS v4.7.1 servido desde Navega.do con cache inmutable. Sin dependencia de CDN externos.

Vía script tag (recomendado)

<!-- CSS + JS desde Navega.do -->
<link rel="stylesheet" href="https://api.navega.do/vendor/maplibre/maplibre-gl.css">
<script src="https://api.navega.do/vendor/maplibre/maplibre-gl.js"></script>

<div id="map" style="width: 100%; height: 500px;"></div>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://api.navega.do/styles/dark?key=TU_API_KEY',
    center: [-69.93, 18.48],
    zoom: 12,
  });

  // Añadir controles
  map.addControl(new maplibregl.NavigationControl());
  map.addControl(new maplibregl.ScaleControl({ maxWidth: 150 }));

  // Añadir marcador
  new maplibregl.Marker()
    .setLngLat([-69.93, 18.48])
    .addTo(map);
</script>

Vía npm (para bundlers)

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: `https://api.navega.do/styles/dark?key=${API_KEY}`,
  center: [-69.93, 18.48],
  zoom: 12,
});

Estilos disponibles: dark, light, streets — Todos incluyen edificios 3D, road casings, aerovías, flechas de sentido y labels en español.

Leaflet

Si prefieres Leaflet, usa el plugin maplibre-gl-leaflet para renderizar los estilos vectoriales de Navega.do.

<!-- 1. Estilos -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<link rel="stylesheet" href="https://api.navega.do/vendor/maplibre/maplibre-gl.css">

<!-- 2. MapLibre GL (debe cargarse antes que su plugin) -->
<script src="https://api.navega.do/vendor/maplibre/maplibre-gl.js"></script>

<!-- 3. Leaflet -->
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

<!-- 4. Plugin (depende de MapLibre GL + Leaflet) -->
<script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.20/leaflet-maplibre-gl.js"></script>

<script>
  const map = L.map('map').setView([18.48, -69.93], 12);

  L.maplibreGL({
    style: 'https://api.navega.do/styles/streets?key=TU_API_KEY'
  }).addTo(map);
</script>

Códigos de Error

Código	Significado
`401`	API key faltante
`403`	API key inválida, revocada, o origen no permitido
`404`	Tile o estilo no encontrado
`429`	Cuota mensual excedida
`502`	Tile server no disponible