Skip to content
Guidez DocsGuidez DocsGuidez Docs

API reference

Base URL: https://api.guidez.app/developer-api/v1

Every request sends the key in the Authorization header. Responses are JSON with camelCase fields. Times are ISO-8601 in UTC.

Authorization: Bearer gz_live_...

New to the API? Start with Developer API to get a key.

List maps

Section titled “List maps”
GET /maps

The creator’s published maps, in the order the creator arranged them. Each item is a map preview.

Terminal window
curl https://api.guidez.app/developer-api/v1/maps \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"

Get a map

Section titled “Get a map”
GET /maps/{mapId}

One map preview, by the mapId from the list.

Terminal window
curl https://api.guidez.app/developer-api/v1/maps/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"

Map preview

Section titled “Map preview”
{
  "mapId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
  "title": "Lisbon Food Crawl",
  "subtitle": "24 tried-and-true stops",
  "description": "Every stop worth your appetite.",
  "coverUrl": "https://media.guidez.app/...",
  "placeCount": 24,
  "isPaid": true,
  "priceCents": 4900,
  "currency": "ILS",
  "landingPageUrl": "https://web.guidez.app/map-preview/lisbon-food-crawl-3f2a9c1e5b7d",
  "mapUrl": "https://web.guidez.app/map/lisbon-food-crawl-3f2a9c1e5b7d",
  "isHidden": false,
  "updatedAt": "2026-10-20T08:14:03"
}
Field Notes
title, subtitle, description From the map’s landing page when it has one, otherwise from the map. subtitle and description can be null.
coverUrl The landing page cover, or a photo from the map when there is none. Can be null.
isPaid true when the map is sold. priceCents and currency are null for free maps.
landingPageUrl The map’s sales page on Guidez. Point “Get the map” buttons here. null when the map has no published landing page.
mapUrl Opens the map itself on Guidez.
isHidden Published, but not shown on the creator’s Guidez profile.

The preview never includes the map’s places. Travelers get those on Guidez.

Get a map’s sales

Section titled “Get a map’s sales”
GET /maps/{mapId}/sales

Completed sales of the map over time, grouped into periods. Test purchases and refunds are left out.

Query parameter Default Notes
start 30 days before end ISO-8601 date and time, included. UTC when no offset is given.
end Now ISO-8601 date and time, not included. Must be after start.
interval day day, week (Monday to Sunday), or month, in UTC.
Terminal window
curl "https://api.guidez.app/developer-api/v1/maps/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f/sales?start=2026-03-01T00:00:00Z&end=2026-04-01T00:00:00Z&interval=week" \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"
{
  "mapId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
  "start": "2026-03-01T00:00:00",
  "end": "2026-04-01T00:00:00",
  "interval": "week",
  "totalSalesCount": 7,
  "totalRevenueCents": { "ILS": 34300 },
  "buckets": [
    { "start": "2026-02-23T00:00:00", "salesCount": 1, "revenueCents": { "ILS": 4900 } },
    { "start": "2026-03-02T00:00:00", "salesCount": 0, "revenueCents": {} },
    { "start": "2026-03-09T00:00:00", "salesCount": 4, "revenueCents": { "ILS": 19600 } },
    { "start": "2026-03-16T00:00:00", "salesCount": 0, "revenueCents": {} },
    { "start": "2026-03-23T00:00:00", "salesCount": 2, "revenueCents": { "ILS": 9800 } },
    { "start": "2026-03-30T00:00:00", "salesCount": 0, "revenueCents": {} }
  ]
}
  • Every period has a bucket, with 0 when nothing sold, so you can chart the list as it comes.
  • A bucket’s start is the start of its day, week, or month, so the first one can begin before your start. Only sales inside your range are counted.
  • Revenue is per currency. revenueCents maps a currency code to the amount buyers paid, before fees, because a map can sell in more than one currency.
  • At most 1000 buckets per request. For long ranges, use week or month.

Errors

Section titled “Errors”

Errors return JSON with a detail message.

Status Meaning
401 The key is missing, wrong, or revoked.
404 The map is not this creator’s, or it is not published.
422 A parameter is invalid, such as start after end or too many buckets.
429 More than 120 requests a minute with this key. Retry after the Retry-After seconds.