# get_spot

One spot with its photos, chapters and routes.

`GET /v1/spots/{spotId}` · MCP tool `get_spot` · scope `read` · stable · since 2026-09-17

The editor view of a spot: every field plus the photos, the chapters it belongs to and the routes that reach it.

## Path parameters

- `spotId` (string, required): Id of the spot (spotId from list_spots).

## Returns

200: SpotDetail.

- `spotId` (string, required): The spot's id.
- `spotKey` (string, required): The spot's stable key within the guide; chapters and routes reference spots by it.
- `productId` (string, required): The guide the spot belongs to.
- `title` (string, required): The place name.
- `kicker` (string or null, required): The short line above the title (region or type).
- `lat` (number or null, required): Latitude in decimal degrees, or null when the pin is not set yet.
- `lon` (number or null, required): Longitude in decimal degrees, or null when the pin is not set yet.
- `mapsUrl` (string or null, required): The creator's own map link.
- `shortDescription` (string or null, required): One or two sentences for the card.
- `longDescription` (string or null, required): The full write-up.
- `color` (string or null, required): Pin color as a hex value, or null for the default.
- `cardOrientation` (string, required): Photo framing in the viewer. One of `portrait`, `landscape`.
- `customValues` (map of values, required): Custom property values keyed by property key; option values are option ids.
- `tripFacts` (TripFacts or null, required): The planning stats bar.
  Fields of TripFacts: https://developers.sceniq.earth/fields/trip-facts.md
- `arrival` (Arrival or null, required): How to get there.
  Fields of Arrival: https://developers.sceniq.earth/fields/arrival.md
- `mapLinks` (array of MapLink, required): Extra map links, drawn as map pills.
  Fields of MapLink: https://developers.sceniq.earth/fields/map-link.md
- `imagesEnabled` (boolean, required): false hides the photo section from buyers.
- `customPropsEnabled` (boolean, required): false hides the custom properties from buyers.
- `archived` (boolean, required): true when the spot is hidden from buyers but kept.
- `ref` (string or null, required): Your own stable key for upsert_spots.
- `accessMode` (string or null, required): How visitors reach the spot, shown as Accessibility. One of `drive_up`, `short_walk`, `hike`, `multi_day`, `boat`, `cable_car`, `train`, `flight`, `tour_only`, `aerial_only`.
- `pinLabel` (string or null, required): What the main pin marks, for a spot that is an area or a line.
- `pins` (array of SpotPin, required): Extra points: viewpoints, entrances, trailheads, parking.
  Fields of SpotPin: https://developers.sceniq.earth/fields/spot-pin.md
- `links` (array of GuideLink, required): Links with a purpose.
  Fields of GuideLink: https://developers.sceniq.earth/fields/guide-link.md
- `status` (StatusNotice or null, required): A closure or works notice.
  Fields of StatusNotice: https://developers.sceniq.earth/fields/status-notice.md
- `fees` (array of Fee, required): Fees and tickets.
  Fields of Fee: https://developers.sceniq.earth/fields/fee.md
- `schedule` (Schedule or null, required): Structured opening hours.
  Fields of Schedule: https://developers.sceniq.earth/fields/schedule.md
- `features` (array of SpotFeature, required): Parts of the site with their own rules.
  Fields of SpotFeature: https://developers.sceniq.earth/fields/spot-feature.md
- `restrictions` (array of Restriction, required): Rules on site.
  Fields of Restriction: https://developers.sceniq.earth/fields/restriction.md
- `events` (array of SpotEvent, required): Events worth timing a visit for.
  Fields of SpotEvent: https://developers.sceniq.earth/fields/spot-event.md
- `food` (FoodNote or null, required): Why the spot lists no food places.
  Fields of FoodNote: https://developers.sceniq.earth/fields/food-note.md
- `areaId` (string or null, required): The area (park, island, region) the spot sits in.
- `timeZone` (string or null, required): IANA time zone, derived from the pin unless set by hand.
- `timeZoneManual` (boolean, required): true when the time zone was set by hand rather than from the pin.
- `customNotes` (map of strings, required): One short note per custom property value, keyed by property key.
- `sources` (array of SourceRef, required): Research evidence for the review, never shown to buyers.
  Fields of SourceRef: https://developers.sceniq.earth/fields/source-ref.md
- `reviewNotes` (string or null, required): Notes for the creator's review, never shown to buyers.
- `factsCheckedOn` (string or null, required): The day the facts were last checked (YYYY-MM-DD).
- `reviewBy` (string or null, required): The day the facts need a new check (YYYY-MM-DD).
- `siteChange` (SiteChange or null, required): The day something at the spot changed.
  Fields of SiteChange: https://developers.sceniq.earth/fields/site-change.md
- `createdAt` (number, required): When the row was created (Unix time in milliseconds).
- `updatedAt` (number, required): When the row last changed (Unix time in milliseconds).
- `photos` (array of objects, required): The spot's photos in gallery order. list_media has every photo field.
  - `mediaId` (string, required): The photo's id.
  - `url` (string, required): The photo's URL.
  - `caption` (string or null, required): Caption.
  - `credit` (string or null, required): Photographer credit.
  - `width` (number or null, required): Width in pixels.
  - `height` (number or null, required): Height in pixels.
  - `order` (number, required): Position in the spot's gallery (ascending).
- `chapters` (array of objects, required): The chapters and collections the spot belongs to.
  - `collectionId` (string, required): The chapter's or collection's id.
  - `name` (string, required): Its name.
  - `kind` (string, required): chapter carries prose; collection is a plain spot set. One of `collection`, `chapter`.
  - `order` (number, required): The spot's position inside that chapter.
- `routes` (array of objects, required): The routes that reach the spot.
  - `routeId` (string, required): The route's id.
  - `name` (string or null, required): The route's name.
  - `order` (number, required): The spot's position on the route.
  - `quickest` (boolean, required): true when this route is the fastest approach to the spot.

## Examples

### Read a spot with its photos, chapters and routes

```bash
curl "https://sceniq.earth/api/v1/spots/k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_spot",
    "arguments": {
      "spotId": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c"
    }
  }
}
```

Response 200:

```json
{
  "spotId": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c",
  "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "title": "Grand Prismatic Spring",
  "kicker": "Yellowstone, Midway Geyser Basin",
  "lat": 44.5251,
  "lon": -110.8382,
  "mapsUrl": "https://maps.apple.com/?ll=44.5251,-110.8382&q=Grand%20Prismatic%20Spring",
  "shortDescription": "The largest hot spring in the United States. See it from the boardwalk, then from the overlook above the Fairy Falls trail.",
  "longDescription": "Grand Prismatic is about 110 meters across, and from the boardwalk you mostly see steam and the orange mats that run off toward the Firehole River. For the colors, park at the Fairy Falls trailhead and follow the trail to the signed spur for the overlook: about 1 km each way, 20 minutes up. The whole spring opens up below the platform. Come on a warm, dry morning; on a cold day the steam hides everything.",
  "color": null,
  "cardOrientation": "landscape",
  "customValues": {
    "best_time": "morning",
    "crowds": "packed",
    "photo_notes": "From the overlook a 24 mm lens takes in the whole spring. On the boardwalk, shoot the runoff channels instead of the steam."
  },
  "tripFacts": {
    "elevationM": 2176,
    "elevationRefersTo": "ground",
    "busyness": 5,
    "bestSeason": "Late May to September"
  },
  "arrival": {
    "byCar": {
      "directions": "Grand Loop Road, 11 km north of Old Faithful. Midway Geyser Basin lot.",
      "parking": "Midway Geyser Basin lot, full by 10:00 in summer. Fairy Falls trailhead lot 1.6 km south.",
      "walkToSpotMin": 10
    },
    "byTrainBus": {
      "none": true
    },
    "bestTime": "Mid morning on a warm, dry day: cold air turns the steam into fog that hides the colors."
  },
  "mapLinks": [],
  "imagesEnabled": true,
  "customPropsEnabled": true,
  "archived": false,
  "ref": null,
  "accessMode": "short_walk",
  "pinLabel": null,
  "pins": [
    {
      "kind": "viewpoint",
      "label": "Grand Prismatic Overlook",
      "lat": 44.5192,
      "lon": -110.8391,
      "note": "Platform on a spur of the Fairy Falls trail, about 1 km from the trailhead lot."
    },
    {
      "kind": "parking",
      "label": "Fairy Falls trailhead lot",
      "lat": 44.5153,
      "lon": -110.8325,
      "note": "For the overlook. Full by mid morning in July and August."
    }
  ],
  "links": [
    {
      "kind": "official",
      "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
      "label": "Grand Prismatic Spring (NPS)"
    },
    {
      "kind": "status",
      "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
      "label": "Park road status"
    }
  ],
  "status": null,
  "fees": [],
  "schedule": null,
  "features": [],
  "restrictions": [
    {
      "kind": "no_drone",
      "label": "No drones in the park",
      "note": "Drones are banned in all US national parks."
    },
    {
      "kind": "no_entry",
      "label": "Stay on the boardwalk",
      "note": "The crust around the spring is thin, and the water under it is scalding."
    }
  ],
  "events": [],
  "food": null,
  "areaId": "area_01m3gvdap06m6mx2kp4t553d6g",
  "timeZone": "America/Denver",
  "timeZoneManual": false,
  "customNotes": {
    "crowds": "Quieter before 9:00 and after 18:00"
  },
  "sources": [
    {
      "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
      "kind": "page",
      "capturedOn": "2026-09-20",
      "supports": [
        "arrival",
        "restrictions"
      ]
    }
  ],
  "reviewNotes": "The overlook pin comes from your GPX of 18 September; please confirm it. The trail distance is from the NPS page (0.6 mi each way).",
  "factsCheckedOn": "2026-09-20",
  "reviewBy": "2027-04-01",
  "siteChange": null,
  "createdAt": 1789895640000,
  "updatedAt": 1790586840000,
  "photos": [
    {
      "mediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-overlook.webp",
      "caption": "From the overlook on a clear September morning",
      "credit": "Mara Lindgren",
      "width": 2048,
      "height": 1365,
      "order": 1
    },
    {
      "mediaId": "kg7p2p4j6v8y0t2r4e6w8q0a2s4d6f8g",
      "url": "https://quiet-heron-512.convex.cloud/api/storage/grand-prismatic-aerial.webp",
      "caption": "Runoff channels from the boardwalk",
      "credit": "Mara Lindgren",
      "width": 1365,
      "height": 2048,
      "order": 2
    }
  ],
  "chapters": [
    {
      "collectionId": "kn7e5r9t3y7v1j5p9p3a7s1d5f9g3h7j",
      "name": "Yellowstone",
      "kind": "chapter",
      "order": 1024
    },
    {
      "collectionId": "kn7a2s4d6f8g0h2j4k6k8z0x2c4v6b8n",
      "name": "Top picks",
      "kind": "collection",
      "order": 1024
    }
  ],
  "routes": [
    {
      "routeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
      "name": "Fairy Falls trail",
      "order": 1024,
      "quickest": false
    }
  ]
}
```

## Errors

- `invalid_argument` (400): A required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message).
- `unauthenticated` (401): The request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
- `invalid_api_key` (401): The key is unknown, revoked or expired.
- `forbidden` (403): The key belongs to a creator account that is no longer active.
- `not_found` (404): The id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
- `rate_limited` (429): Over a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
- `internal_error` (500): An unexpected failure. The message is hidden on purpose.

Reference: https://developers.sceniq.earth/reference/get_spot