# set_area

Create an area, or replace one area's content.

`PUT /v1/guides/{productId}/areas` · MCP tool `set_area` · scope `write` · beta · since 2026-09-30

Rules that apply to a whole park, island or region (Yellowstone's fee and road season, Rapa Nui's entry form, Tibet's permit) live once here; spots point at it with update_spot areaId and buyers see it on each spot. Without areaId this creates an area and returns its id; with areaId every field is replaced (fields you leave out are cleared). At most 50 per guide.

## Path parameters

- `productId` (string, required): Id of the guide (a product of type map). From list_guides or create_guide.

## Body parameters

- `name` (string, required): The area's name, at most 100 characters, e.g. Yellowstone National Park.
- `areaId` (string, optional): The area to replace (from list_areas); omit to create one.
- `fees` (array of Fee, optional): Fees and tickets, full replacement ([] clears), at most 30: [{ label, amount? (major units, e.g. 40 or 12.5; needs currency), currency? (EUR), free?, seeOfficial? (a price left to the official page on purpose), per?: person|vehicle|night|group|entry|day|hour, audience?: all|adult|child|foreign|domestic|resident|student|senior, paidWhere?: online|on_site|in_tour, payment?: cash_only|card_only|cash_or_card, note?, validFrom?, validUntil?, sourceUrl?, checkedOn? }]. Buyers see the amount with an as-of date; readiness flags rows past validUntil or unchecked for a year.
  Fields of Fee: https://developers.sceniq.earth/fields/fee.md
- `kind` (string, optional): park, reserve, island, region, city or other. One of `park`, `reserve`, `island`, `region`, `city`, `other`.
- `links` (array of GuideLink, optional): Links with a purpose, full replacement ([] clears), at most 12: [{ kind: official|website|tickets|booking|status|timetable|tide|listing|social|authority|app|other, label?, url? (http or https; http is accepted with a warning), value? (a channel that is not a URL, e.g. WeChat mini program: Li River boats), note? }]. Each needs a url or a value.
  Fields of GuideLink: https://developers.sceniq.earth/fields/guide-link.md
- `note` (string, optional): What applies across the area, in the creator's words, at most 1,000 characters.
- `rules` (array of AccessRule, optional): [{ text, kind?, months?, appliesTo?, bookingOpens?, sourceUrl? }], as arrival.rules.
  Fields of AccessRule: https://developers.sceniq.earth/fields/access-rule.md
- `season` (string, optional): The area's season in words, at most 300 characters (roads open May to October).
- `sources` (array of SourceRef, optional): Research evidence for reviewers, never shown to buyers; full replacement, at most 40: [{ url? or title?, kind?: page|api|archive|document|other, capturedOn?, note?, supports? (which facts it backs, e.g. fees, arrival.operating, lat/lon), conflict? (true when it disagrees with another source on those facts) }].
  Fields of SourceRef: https://developers.sceniq.earth/fields/source-ref.md
- `status` (StatusNotice, optional): Closure or works notice for the whole area: { state: open|partly_closed|closed|reopening, note?, since?, until?, sourceUrl?, checkedOn? }. set_area replaces every field, so leave it out to clear it (null is not accepted).
  Fields of StatusNotice: https://developers.sceniq.earth/fields/status-notice.md

## Returns

200.

- `productId` (string, required): The guide's id.
- `created` (boolean, required): true when this call created the area.
- `area` (AreaWithSpots or null, required): The area as stored.
  Fields of AreaWithSpots: https://developers.sceniq.earth/fields/area-with-spots.md
- `warnings` (array of strings, optional): Notes about things the write accepted but you should look at (a plain http link). Present only when there are any.

## Examples

### Create an area for a whole park (no areaId)

```bash
curl -X PUT "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/areas" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Yellowstone National Park",
  "kind": "park",
  "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
  "season": "Most park roads are open to cars from May to early November.",
  "rules": [
    {
      "text": "Stay on boardwalks and marked trails in every thermal area.",
      "kind": "other",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
    }
  ],
  "fees": [
    {
      "label": "Park entrance, private vehicle, 7 days",
      "amount": 35,
      "currency": "USD",
      "per": "vehicle",
      "paidWhere": "online",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "checkedOn": "2026-09-20"
    }
  ],
  "links": [
    {
      "kind": "official",
      "url": "https://www.nps.gov/yell/index.htm",
      "label": "Yellowstone National Park (NPS)"
    },
    {
      "kind": "status",
      "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
      "label": "Park road status"
    }
  ],
  "sources": [
    {
      "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "kind": "page",
      "capturedOn": "2026-09-20",
      "supports": [
        "fees"
      ]
    }
  ]
}'
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_area",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Yellowstone National Park",
      "kind": "park",
      "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
      "season": "Most park roads are open to cars from May to early November.",
      "rules": [
        {
          "text": "Stay on boardwalks and marked trails in every thermal area.",
          "kind": "other",
          "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
        }
      ],
      "fees": [
        {
          "label": "Park entrance, private vehicle, 7 days",
          "amount": 35,
          "currency": "USD",
          "per": "vehicle",
          "paidWhere": "online",
          "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
          "checkedOn": "2026-09-20"
        }
      ],
      "links": [
        {
          "kind": "official",
          "url": "https://www.nps.gov/yell/index.htm",
          "label": "Yellowstone National Park (NPS)"
        },
        {
          "kind": "status",
          "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
          "label": "Park road status"
        }
      ],
      "sources": [
        {
          "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
          "kind": "page",
          "capturedOn": "2026-09-20",
          "supports": [
            "fees"
          ]
        }
      ]
    }
  }
}
```

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "created": true,
  "area": {
    "id": "area_01m3gvdap06m6mx2kp4t553d6g",
    "name": "Yellowstone National Park",
    "kind": "park",
    "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
    "season": "Most park roads are open to cars from May to early November.",
    "rules": [
      {
        "text": "Stay on boardwalks and marked trails in every thermal area.",
        "kind": "other",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
      }
    ],
    "fees": [
      {
        "label": "Park entrance, private vehicle, 7 days",
        "amount": 35,
        "currency": "USD",
        "per": "vehicle",
        "paidWhere": "online",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "checkedOn": "2026-09-20"
      }
    ],
    "links": [
      {
        "kind": "official",
        "url": "https://www.nps.gov/yell/index.htm",
        "label": "Yellowstone National Park (NPS)"
      },
      {
        "kind": "status",
        "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
        "label": "Park road status"
      }
    ],
    "sources": [
      {
        "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "kind": "page",
        "capturedOn": "2026-09-20",
        "supports": [
          "fees"
        ]
      }
    ],
    "spotKeys": []
  }
}
```

### Replace an area's content (fields left out are cleared)

```bash
curl -X PUT "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/areas" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "areaId": "area_01m3gvgcb04pf38p66vz544w1b",
  "name": "Yosemite National Park",
  "kind": "park",
  "season": "Open all year. Glacier Point Road and Tioga Road close to cars in winter.",
  "rules": [
    {
      "text": "Glacier Point Road and Tioga Road are closed to cars in winter, usually from November to late May.",
      "kind": "vehicle",
      "months": [
        11,
        12,
        1,
        2,
        3,
        4,
        5
      ],
      "appliesTo": "car",
      "sourceUrl": "https://www.nps.gov/yose/planyourvisit/conditions.htm"
    }
  ],
  "fees": [
    {
      "label": "Park entrance, private vehicle, 7 days",
      "amount": 35,
      "currency": "USD",
      "per": "vehicle",
      "sourceUrl": "https://www.nps.gov/yose/planyourvisit/fees.htm",
      "checkedOn": "2026-09-20"
    }
  ],
  "links": [
    {
      "kind": "official",
      "url": "https://www.nps.gov/yose/index.htm",
      "label": "Yosemite National Park (NPS)"
    },
    {
      "kind": "timetable",
      "url": "https://yarts.com/",
      "label": "YARTS buses into the valley"
    }
  ]
}'
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_area",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "areaId": "area_01m3gvgcb04pf38p66vz544w1b",
      "name": "Yosemite National Park",
      "kind": "park",
      "season": "Open all year. Glacier Point Road and Tioga Road close to cars in winter.",
      "rules": [
        {
          "text": "Glacier Point Road and Tioga Road are closed to cars in winter, usually from November to late May.",
          "kind": "vehicle",
          "months": [
            11,
            12,
            1,
            2,
            3,
            4,
            5
          ],
          "appliesTo": "car",
          "sourceUrl": "https://www.nps.gov/yose/planyourvisit/conditions.htm"
        }
      ],
      "fees": [
        {
          "label": "Park entrance, private vehicle, 7 days",
          "amount": 35,
          "currency": "USD",
          "per": "vehicle",
          "sourceUrl": "https://www.nps.gov/yose/planyourvisit/fees.htm",
          "checkedOn": "2026-09-20"
        }
      ],
      "links": [
        {
          "kind": "official",
          "url": "https://www.nps.gov/yose/index.htm",
          "label": "Yosemite National Park (NPS)"
        },
        {
          "kind": "timetable",
          "url": "https://yarts.com/",
          "label": "YARTS buses into the valley"
        }
      ]
    }
  }
}
```

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "created": false,
  "area": {
    "id": "area_01m3gvgcb04pf38p66vz544w1b",
    "name": "Yosemite National Park",
    "kind": "park",
    "season": "Open all year. Glacier Point Road and Tioga Road close to cars in winter.",
    "rules": [
      {
        "text": "Glacier Point Road and Tioga Road are closed to cars in winter, usually from November to late May.",
        "kind": "vehicle",
        "months": [
          11,
          12,
          1,
          2,
          3,
          4,
          5
        ],
        "appliesTo": "car",
        "sourceUrl": "https://www.nps.gov/yose/planyourvisit/conditions.htm"
      }
    ],
    "fees": [
      {
        "label": "Park entrance, private vehicle, 7 days",
        "amount": 35,
        "currency": "USD",
        "per": "vehicle",
        "sourceUrl": "https://www.nps.gov/yose/planyourvisit/fees.htm",
        "checkedOn": "2026-09-20"
      }
    ],
    "links": [
      {
        "kind": "official",
        "url": "https://www.nps.gov/yose/index.htm",
        "label": "Yosemite National Park (NPS)"
      },
      {
        "kind": "timetable",
        "url": "https://yarts.com/",
        "label": "YARTS buses into the valley"
      }
    ],
    "spotKeys": [
      "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
      "01M3H2AWH0F9PB64V7QB8QS0MC",
      "01M3H2AXG8GB8YNF4FCEFARFN5",
      "01M3H2AYFG8169CVH0JCQY2BN2"
    ]
  }
}
```

## 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).
- `invalid_request` (400): A writer refused a value: a map link on a host that is not allowed, a title that is too long, a date that does not exist, too many items in a list. The message is the writer's own sentence.
- `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.
- `api_scope_required` (403): A read-only key called a write operation, or a key without the publish option called publish_changes.
- `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.
- `payload_too_large` (413): A JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
- `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/set_area