@eviav/api-client

Cliente HTTP oficial de Eviav — TypeScript tipado para los 18 servicios: geocoding, ruteo, mapas, tiles, IA. Funciona en Node 20+, Bun, Deno y browser moderno.

npm install @eviav/api-client

Quickstart

import { EviavClient } from "@eviav/api-client";

const eviav = new EviavClient({
  apiKey: process.env.EVIAV_API_KEY!,
});

// Geocoding
const g = await eviav.geocode("Av. Amazonas, Quito");
console.log(g.results[0]);  // { name, lat, lon, type }

// Routing
const r = await eviav.directions([
  [-78.51, -0.22],  // [lon, lat] (GeoJSON)
  [-78.48, -0.18],
]);
console.log(r.routes[0].distance, "m,", r.routes[0].duration, "s");

// Places
const p = await eviav.places(-0.18, -78.48, "restaurant", { radius: 1000, limit: 20 });

// Fleet routing
const f = await eviav.fleet({
  vehicles: [{ id: 1, start: [-78.51, -0.22], end: [-78.51, -0.22], capacity: [50] }],
  jobs: [{ id: 1, location: [-78.48, -0.12], amount: [5] }],
});

// Isochrone (cobertura por tiempo)
const iso = await eviav.isochrone(-0.18, -78.48, { contours: "10,20,30", costing: "auto" });

// Maps Grounding (LLM con contexto del mapa)
const ai = await eviav.grounding("cafeterías cerca de la Plaza Foch", { lat: -0.18, lon: -78.48 });

Métodos disponibles

Search

• geocode(q, opts?) — dirección → coordenadas
• reverse(lat, lon) — coordenadas → dirección
• search(text, opts?) — autocompletado typeahead
• autofill(text, opts?) — búsqueda con componentes de dirección
• places(lat, lon, category, opts?) — POIs por categoría
• geocodeBatch(queries, opts?) — hasta 100 consultas en una request

Routing

• directions(coordinates, opts?) — ruta multi-waypoint
• matrix(sources, destinations?) — matriz NxM tiempos/distancias
• optimize(coordinates, opts?) — TSP single-vehicle
• fleet(body) — VROOM multi-vehículo con restricciones
• match(coordinates) — map matching (snap GPS a la red)
• nearest(point, opts?) — vía más cercana

Data

• isochrone(lat, lon, opts?) — áreas alcanzables por tiempo
• timezone(lat, lon) — zona horaria IANA
• elevation(lat, lon) — altitud en metros
• tilequery(lat, lon, opts?) — features OSM cercanos

Maps

• staticMap(opts) — PNG renderizado (Uint8Array)
• tile(tileset, z, x, y, ext?) — tile vector/raster crudo

Datasets

• listDatasets(opts?) — catálogo de tilesets de tu org
• customTile(id, z, x, y) — tile de un tileset privado

AI

• grounding(query, opts?) — LLM con contexto del mapa
• aiChat(message, opts?), aiTrip(places, opts?), aiVision(image, opts?)

Manejo de errores

El cliente lanza EviavError cuando el gateway responde 4xx/5xx (con retries automáticos para 429 y 5xx):

import { EviavError } from "@eviav/api-client";

try {
  const r = await eviav.geocode("...");
} catch (err) {
  if (err instanceof EviavError) {
    console.error(err.status, err.code, err.message, "request:", err.requestId);
    // Reportá el requestId a [email protected] si es un bug.
    if (err.code === "rate_limited") {
      console.log("Esperá", err.retryAfterSec, "s");
    }
  }
}

Configuración

const eviav = new EviavClient({
  apiKey: "...",
  baseUrl: "https://api.eviav.com",  // default
  timeoutMs: 20000,                  // default 20s
  retries: 3,                        // default 3 (429 + 5xx)
  fetch: customFetch,                // opcional, default global fetch
});

Recursos

• 📖 Documentación completa: https://eviav.com/docs
• 💬 Soporte: [email protected]
• 🐛 Issues: https://github.com/eviav/sdk-js/issues

Licencia

MIT