@mappify/sdk

Official Mappify SDK for JavaScript and TypeScript.

Installation

npm install @mappify/sdk
# or
yarn add @mappify/sdk
# or
pnpm add @mappify/sdk

Requirements

• Node.js 18+
• TypeScript 4.5+ (optional but recommended)

Quick Start

import { MappifyClient } from '@mappify/sdk';

const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY!,
  environment: 'sandbox', // or 'production'
});

// Create a route
const route = await client.routes.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  destination: { lat: 41.4036, lng: 2.1744 },
  profile: 'driving',
  optimize_for: 'time',
});

console.log('Distance:', route.distance_meters, 'meters');
console.log('Duration:', route.duration_seconds, 'seconds');

Features

Routes API

Create routes between coordinates with various options.

const route = await client.routes.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  destination: { lat: 41.4036, lng: 2.1744 },
  waypoints: [{ lat: 41.39, lng: 2.17 }],
  profile: 'driving_delivery',
  optimize_for: 'time',
  avoid: { tolls: true },
});

Optimizations API (Beta)

Multi-stop route optimization.

const optimization = await client.optimizations.create({
  origin: { lat: 41.3874, lng: 2.1686 },
  stops: [
    { lat: 41.39, lng: 2.17 },
    { lat: 41.40, lng: 2.18 },
    { lat: 41.41, lng: 2.16 },
  ],
  profile: 'driving_delivery',
});

console.log('Optimized order:', optimization.optimized_order);

Navigation API

Real-time navigation sessions with turn-by-turn guidance.

// Create a session
const session = await client.navigation.createSession({
  route_id: route.route_id,
  driver_id: 'driver_123',
});

// Update with device location
const state = await client.navigation.updateSession(session.session_id, {
  position: { lat: 41.388, lng: 2.169 },
});

console.log('Next instruction:', state.current_step.instruction);
console.log('ETA:', state.eta);

Signals API

Get traffic, incidents, and signals data.

// Signals around a position
const signals = await client.signals.getSignals({
  lat: 41.3874,
  lng: 2.1686,
  radius_meters: 300,
  types: ['congestion', 'incident'],
});

// Signals along a route
const routeSignals = await client.signals.getSignalsForRoute({
  route_id: route.route_id,
});

Telemetry API

Send driver and device events.

await client.telemetry.sendEvent({
  event_type: 'navigation_started',
  session_id: session.session_id,
  driver_id: 'driver_123',
  position: { lat: 41.3874, lng: 2.1686 },
});

Error Handling

import { MappifyApiError } from '@mappify/sdk';

try {
  const route = await client.routes.create({ /* ... */ });
} catch (error) {
  if (error instanceof MappifyApiError) {
    console.error('API Error:', {
      status: error.status,
      type: error.type,
      message: error.message,
      requestId: error.requestId,
    });
  }
}

Configuration

const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY!,
  environment: 'sandbox',
  timeoutMs: 10000, // Optional: request timeout
  baseUrlOverride: 'https://custom.api.com/v1', // Optional: for enterprise
});

CommonJS

const { MappifyClient } = require('@mappify/sdk');

const client = new MappifyClient({
  apiKey: process.env.MAPPIFY_API_KEY,
  environment: 'sandbox',
});

Documentation

Full documentation available at mappify.app/docs/sdks/javascript

License

MIT © Mappify