Maimaps API

Overview

The Maimaps API powers full map experiences: render vector maps, search places and addresses, compute drive/walk/cycle routes, reverse-geocode coordinates, resolve tapped points, and look up Maiaddy loccodes — all authenticated with a single MAIMAPS API key.

Every successful REST response uses a stable envelope:

{ "status": "success", "message": "...", "data": { ... } }

Route responses are OSRM-shaped (routes[].distance|duration|geometry|legs); polylines use precision 5. /sdk/v1 is the stable contract — breaking changes require /sdk/v2; additive fields are non-breaking.

Quickstart

From zero to a rendered map with your first search and route in three steps.

Replace mk_test_your_key with a key from the console.

import { MaimapsClient } from "@maimaps/js";
import maplibregl from "maplibre-gl";

const client = new MaimapsClient({ apiKey: "mk_test_your_key" });

// 1. Render a map (each keyed style.json fetch = one map load)
const map = new maplibregl.Map({
  container: "map",
  style: client.styleUrl({ mode: "dark" }),
  transformRequest: (url) => ({ url: client.transformMapResource(url) }),
});

// 2. First search
const results = await client.search({
  q: "garki market",
  latitude: 9.05,
  longitude: 7.49,
});

// 3. First route (OSRM-shaped: routes[].distance|duration|geometry|legs)
const trip = await client.route({
  originLat: 9.05,
  originLng: 7.49,
  destLat: 6.45,
  destLng: 3.39,
  mode: "drive",
});

Authentication

Keys are minted in this portal for the MAIMAPS product: mk_live_… for the LIVE environment and mk_test_… for TEST. Pass the key with every request — as the X-Api-Key header (preferred for REST calls) or as a ?key= query parameter (required for map resources, which cannot set headers portably).

GET /sdk/v1/search?q=garki%20market HTTP/1.1
Host: maps-staging-api.maiaddy.com
X-Api-Key: mk_test_your_key

# Map resources can't set headers portably — pass the key as a query param.
GET /sdk/styles/maimaps/style.json?mode=dark&key=mk_test_your_key

Rate limits & quotas

The free tier meters every billable dimension from day one. LIVE keys get the limits below; TEST keys share the same per-second rates with 10% of the monthly caps.

• Tiles are never billed — the map load is the display unit; tile limits exist purely as an abuse guard.
• Per-second limits are enforced at the edge; monthly caps are computed from usage rollups, and an over-quota key is switched off at the next validation refresh (≤ 5 minutes).
• Every limited route returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, plus Retry-After on 429.

Errors

Failures return a stable error body with a machine-readable code:

{ "status": "error", "code": "rate_limited", "message": "Per-key rate limit hit. Retry after 2 seconds." }

The SDKs raise typed errors (InvalidApiKeyError, RateLimitError(retryAfter), QuotaExceededError) and automatically retry idempotent GETs only, honoring Retry-After.

REST endpoints

All REST endpoints live under /sdk/v1 on the API gateway and accept the X-Api-Key header.

Map assets are served from the map host and authenticate with the ?key= query parameter. The style.json references the /sdk/* tile/sprite/glyph URLs; the SDKs append the key via transformRequest / transformMapResource.

SDKs

Official Maimaps SDKs for JavaScript, React, React Native, and Flutter wrap every endpoint, handle key injection on both hosts, and ship typed errors with rate-limit-aware retries.