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 + PMTiles (self-hosted) -->
<link rel="stylesheet" href="https://navega.do/vendor/maplibre/maplibre-gl.css">
<script src="https://navega.do/vendor/maplibre/maplibre-gl.js"></script>
<script src="https://navega.do/vendor/maplibre/pmtiles.js"></script>

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

<script>
  // Registrar protocolo PMTiles (requerido para estilos vectoriales)
  const protocol = new pmtiles.Protocol();
  maplibregl.addProtocol('pmtiles', protocol.tile.bind(protocol));

  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>

100% self-hosted: los tiles, estilos, sprites, iconos y fuentes tipográficas son datos propios de Navega.do — y el archivo de la librería MapLibre GL JS también se sirve desde api.navega.do (con caché inmutable de 1 año) en vez de apuntar a un CDN externo como unpkg o jsdelivr. Tu app nunca hace una sola petición a un tercero para cargar el mapa: ni por los datos, ni por el código del renderizador.

¿Por qué sigo necesitando MapLibre GL JS si todo es propio? MapLibre es el motor de renderizado que corre en el navegador del usuario final: toma el tile vectorial (datos de Navega.do) y lo dibuja en pantalla con WebGL — zoom, paneo, proyección, aceleración por GPU. Es una pieza de software totalmente distinta a los datos del mapa, igual que un navegador necesita un motor de renderizado HTML sin importar quién sea dueño de la página. Ningún proveedor de mapas evita esto — Google Maps también obliga a cargar su propio maps.js en el navegador del cliente. Lo que "self-hosted" cambia aquí es que ese motor lo serviremos nosotros, no un CDN de terceros.

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 — 36 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.

MapLibre es el motor de renderizado WebGL que se ejecuta en el navegador del usuario para dibujar los tiles de Navega.do en pantalla — es una pieza distinta a los datos del mapa, y toda librería de mapas (incluida la de Google Maps) requiere una equivalente en el cliente. Aquí la servimos nosotros mismos en vez de depender de un CDN externo.

Vía script tag (recomendado)

<!-- CSS + JS desde Navega.do (con PMTiles para estilos vectoriales) -->
<link rel="stylesheet" href="https://navega.do/vendor/maplibre/maplibre-gl.css">
<script src="https://navega.do/vendor/maplibre/maplibre-gl.js"></script>
<script src="https://navega.do/vendor/maplibre/pmtiles.js"></script>

<div id="map" style="width: 100%; height: 500px;"></div>
<script>
  // Registrar protocolo PMTiles (requerido para estilos vectoriales)
  const protocol = new pmtiles.Protocol();
  maplibregl.addProtocol('pmtiles', protocol.tile.bind(protocol));

  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';
import * as pmtiles from 'pmtiles';

// Registrar protocolo PMTiles (requerido para estilos vectoriales)
const protocol = new pmtiles.Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile.bind(protocol));

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://navega.do/vendor/maplibre/maplibre-gl.css">

<!-- 2. MapLibre GL + PMTiles (debe cargarse antes que su plugin) -->
<script src="https://navega.do/vendor/maplibre/maplibre-gl.js"></script>
<script src="https://navega.do/vendor/maplibre/pmtiles.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>
  // Registrar protocolo PMTiles
  const protocol = new pmtiles.Protocol();
  maplibregl.addProtocol('pmtiles', protocol.tile.bind(protocol));

  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