DirecciónVE API

Motor de resolución de direcciones para Venezuela. Cada metro cuadrado tiene un Plus Code único.

Instalación

<script src="https://direccionve.org/direccionve.js"></script>

O descárgalo y sírvelo localmente:

<script src="/direccionve.js"></script>

Quick Start

// 1. Cargar datos
const [houses, streets] = await Promise.all([
  fetch('/data-houses.json').then(r => r.json()),
  fetch('/data-streets.json').then(r => r.json())
]);

// 2. Inicializar
DireccionVE.init(houses, streets);

// 3. Buscar
const results = DireccionVE.search('Altamira Caracas');
console.log(results[0]);
// → { address: "Av. Luis Roche, Altamira", code: "67P8GRJ5+XX", lat: 10.5, lng: -66.85 }

// 4. Resolver un Plus Code
const place = DireccionVE.resolve('67P8GRJ5+XX');
console.log(place.address, place.distance + 'm');

Métodos

DireccionVE.init(housesData, streetsData)

Inicializa el motor. Debe llamarse antes de cualquier otra función.

Parámetro	Tipo	Descripción
`housesData`	Array	Array de `[zip, city, street, number, lng, lat]`
`streetsData`	Array	Array de `[city, name, lng, lat]`

Retorna: undefined

DireccionVE.search(query, limit?)

Búsqueda de texto libre. Tokeniza la query y puntúa por coincidencia de tokens.

Parámetro	Tipo	Default	Descripción
`query`	string	—	Texto libre: ciudad, calle, número, CP
`limit`	number	20	Máximo de resultados

Retorna: Array<Result>

DireccionVE.search('los palos grandes', 5);
// → [{ address, code, lat, lng, type }, ...]

DireccionVE.lookup({ city, street, number? })

Búsqueda exacta por ciudad + calle + número opcional.

Parámetro	Tipo	Descripción
`city`	string	Ciudad o localidad
`street`	string	Nombre de la calle
`number`	string	(Opcional) Número de casa

Retorna: Result | null

DireccionVE.lookup({ city: 'Caracas', street: 'Av Libertador', number: '123' });
// → { address: "Av Libertador, #123, Caracas", code: "67P8...", lat, lng }

DireccionVE.resolve(plusCode)

Dado un Plus Code, encuentra la dirección conocida más cercana.

Parámetro	Tipo	Descripción
`plusCode`	string	Plus Code válido (ej: `67P8GRJ5+XX`)

Retorna: ResolveResult | null

DireccionVE.resolve('67P8GRJ5+XX');
// → { address, code, lat, lng, nearestLat, nearestLng, distance }
// distance = metros entre el código y la dirección más cercana

DireccionVE.suggest(partial, limit?)

Autocompletado de calles y ciudades.

Parámetro	Tipo	Default	Descripción
`partial`	string	—	Texto parcial (mín. 2 caracteres)
`limit`	number	10	Máximo sugerencias

Retorna: Array<string>

DireccionVE.suggest('altam');
// → ["Altamira, Av. Luis Roche", "Altamira, Calle Madrid", ...]

DireccionVE.encode(lat, lng, length?)

Convierte coordenadas a Plus Code.

Parámetro	Tipo	Default	Descripción
`lat`	number	—	Latitud (-90 a 90)
`lng`	number	—	Longitud (-180 a 180)
`length`	number	10	Longitud del código (8, 10, 11, 12)

Retorna: string

DireccionVE.encode(10.4961, -66.8509);
// → "67P8GRJ5+XX"

DireccionVE.decode(plusCode)

Decodifica Plus Code a coordenadas.

Parámetro	Tipo	Descripción
`plusCode`	string	Plus Code válido

Retorna: { lat, lng, latLo, lngLo, latHi, lngHi, latR, lngR }

const pos = DireccionVE.decode('67P8GRJ5+XX');
console.log(pos.lat, pos.lng); // 10.4961, -66.8509

DireccionVE.isValidCode(code)

Valida si un string es un Plus Code válido.

Parámetro	Tipo	Descripción
`code`	string	String a validar

Retorna: boolean

DireccionVE.getStats()

Estadísticas del dataset cargado.

Retorna: { houses, streets, cities, uniqueStreets }

DireccionVE.getStats();
// → { houses: 3249, streets: 17351, cities: 412, uniqueStreets: 8920 }

Datos

Los archivos JSON se sirven desde https://direccionve.org/:

Archivo	Registros	Descripción
`data-houses.json`	3,249	Direcciones con número `[zip, city, street, number, lng, lat]`
`data-streets.json`	17,351	Calles `[city, name, lng, lat]`
`data-all-addresses.json`	145,123	Todos los POI de OSM Venezuela
`data-centers.json`	15,748	Centros de votación `[code, name, state, muni, parish, voters, lat, lng, plusCode]`

MIT — Datos de OpenStreetMap (ODbL) y CNE (público).
← Ir al mapa · GitHub