Ambalay Maps Client SDK

Official TypeScript client for authenticated Ambalay Maps services.

Install

npm install @ambalay-maps/client-sdk

Quick Start

import { createAmbalayClient } from '@ambalay-maps/client-sdk'

const client = createAmbalayClient({
  baseUrl: 'https://api.dev.ambalaymaps.com',
  apiKey: 'YOUR_API_KEY',
})

const places = await client.geocoding.search({
  term: 'Addis Ababa',
  limit: 5,
})

API Key Access

API keys can be limited to selected services. Check the available services once when the key changes, then enable only the features the key supports.

const access = await client.apiKey.getAllowedServices()

if (access.allowedServices.includes('GEO_CODING')) {
  const places = await client.geocoding.search({ term: 'Bole', limit: 5 })
}

Geocoding

const results = await client.geocoding.search({
  term: 'Meskel Square',
  limit: 10,
})

const place = await client.geocoding.reverse({
  lat: 8.9806,
  lon: 38.7578,
})

Routing

const route = await client.routing.route({
  source: { lat: 8.9806, lon: 38.7578 },
  destination: { lat: 8.99, lon: 38.76 },
  costing: 'AUTO',
})

Matrix

const matrix = await client.matrix.calculate({
  sources: [{ lat: 8.9806, lon: 38.7578 }],
  targets: [{ lat: 8.99, lon: 38.76 }],
  costing: 'AUTO',
})

Browser Map

import 'maplibre-gl/dist/maplibre-gl.css'
import { createAmbalayMap } from '@ambalay-maps/client-sdk'

const map = createAmbalayMap({
  container: 'map',
  baseUrl: 'https://api.dev.ambalaymaps.com',
  apiKey: 'YOUR_API_KEY',
  center: [38.7578, 8.9806],
  zoom: 12,
})

map.remove()

The SDK uses only authenticated /services/* endpoints. It does not call /public/services/*. Map style configuration is intentionally internal for now.

React Map

import 'maplibre-gl/dist/maplibre-gl.css'
import { AmbalayMap } from '@ambalay-maps/client-sdk/react'

export function MapView() {
  return (
    <AmbalayMap
      baseUrl="https://api.dev.ambalaymaps.com"
      apiKey="YOUR_API_KEY"
      center={[38.7578, 8.9806]}
      zoom={12}
      style={{ height: 500 }}
      onClick={(event) => {
        console.log(event.lat, event.lon)
      }}
    />
  )
}