ZeeMaps API Docs v1

Quickstart

This walkthrough takes you from a fresh API key to your first markers on a map. Every step has a copy-pasteable curl. It should take well under ten minutes.

Before you start

You need:

  1. A ZeeMaps account on the enterprise plan. API access is gated on this plan — a key on any lower plan is rejected with 402 PLAN_REQUIRED. See Authentication for how to request a key and upgrade.
  2. An API key. Keys are minted by ZeeMaps on request and shown to you once. Store it like a password.

Set it as an environment variable so the snippets below just work:

export ZM_KEY="zm_your_api_key_here"
export ZM_API="https://api.zeemaps.com/v1"

Step 1 — Confirm your key works

GET /v1/me is the cheapest authenticated call. It echoes the account, scope, plan, and rate limit behind your key — a good first check and a way for a client to self-configure.

curl -s "$ZM_API/me" \
  -H "Authorization: Bearer $ZM_KEY"

{
  "account_email": "ops@acme.example",
  "scope": "read_write",
  "plan": "enterprise",
  "rate_limit": 30
}

If you get a 401, the key is missing/invalid/revoked. If you get a 402, the key is valid but the account is not on the enterprise plan. Both responses include an error.help_url that deep-links you to the page that fixes it — see Errors and Authentication.

Reference: GET /me.

Step 2 — List your maps

GET /v1/maps returns the maps your account owns (the API is owned-only — maps merely shared with you are not listed; see Conventions).

curl -s "$ZM_API/maps?page_size=10" \
  -H "Authorization: Bearer $ZM_KEY"

{
  "maps": [
    { "id": 4321179, "name": "US Sales Territories Q3 2026", "status": "active", "private": true }
  ],
  "page_info": { "total_count": 1, "next_page_token": null }
}

Reference: GET /maps.

Step 3 — Create a map

A new map needs only a name (and optionally a description). New maps are created private by default; flip that later with PATCH /v1/maps/{map_id}.

curl -s -X POST "$ZM_API/maps" \
  -H "Authorization: Bearer $ZM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Quickstart Demo",
        "description": "Created from the API quickstart"
      }'

{
  "id": 4322001,
  "name": "Quickstart Demo",
  "description": "Created from the API quickstart",
  "owner_email": "ops@acme.example",
  "status": "active",
  "private": true,
  "extended_colors": false,
  "marker_count": 0,
  "region_count": 0,
  "created_at": "2026-06-30T17:00:00Z",
  "updated_at": "2026-06-30T17:00:00Z"
}

Capture the new id for the next step:

export ZM_MAP=4322001

Reference: POST /maps.

Step 4 — Add a marker

Add a pin with coordinates. Only name is required; supply either lat+lng or an address (the server geocodes address-only markers for you).

curl -s -X POST "$ZM_API/maps/$ZM_MAP/markers" \
  -H "Authorization: Bearer $ZM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme Corp HQ",
        "lat": 37.7879,
        "lng": -122.3983,
        "category": "Customer"
      }'

{
  "id": 88341027,
  "map_id": 4322001,
  "name": "Acme Corp HQ",
  "type": "pin",
  "lat": 37.7879,
  "lng": -122.3983,
  "category": "Customer",
  "color": "blue",
  "created_at": "2026-06-30T17:01:00Z"
}

Prefer to add by address only? Drop lat/lng and send a structured address — the server geocodes it:

curl -s -X POST "$ZM_API/maps/$ZM_MAP/markers" \
  -H "Authorization: Bearer $ZM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme Corp HQ",
        "address": { "street": "350 Mission St", "city": "San Francisco", "state": "CA", "zip": "94105" },
        "category": "Customer"
      }'

Reference: POST /maps/{map_id}/markers.

Step 5 — Read your markers

curl -s "$ZM_API/maps/$ZM_MAP/markers?page_size=50" \
  -H "Authorization: Bearer $ZM_KEY"

The list is paginated — follow page_info.next_page_token to walk large maps. See Pagination.

Reference: GET /maps/{map_id}/markers.

Where to next