Developers
MCP available

MCP responses and pagination

The JSON examples below show the tool payload shape of three tools. They are also in examples/mcp/. The MCP content wrapper around these values depends on your client or SDK.

resolve_place: array of candidates

json
{
  "count": 1,
  "has_more": false,
  "items": [{
    "id": "27799", "title": "Madrid", "node_type": "Cities",
    "address_city": "Madrid", "country_code": "ES", "slug_id": "spain/madrid"
  }]
}

Use country_code, node_type and geographic context to disambiguate names like “Soho” or “Springfield”.

find_venues: paged list

json
{
  "count": 15,
  "has_more": true,
  "next_cursor": "<opaque cursor>",
  "items": [{
    "id": "3130457", "title": "El Retiro Park", "node_type": "Attractions",
    "category": "Park", "rating": 4.8, "rating_votes": 193076,
    "address_city": "Madrid", "country_code": "ES"
  }]
}

This excerpt is shortened for readability. In the original example, count is 15 and items contains 15 entries; count is not a guaranteed total number of matches in the entire city. Use has_more and next_cursor to request another page.

get_venue: single detailed record

The provided detail example for Museo Nacional del Prado includes id, slug_id, parent_id, node_type, title, tagline, short_description, HTML description, category, additional_categories, rating, rating_votes, address fields, coordinates, phone, website URL, image URL, total_photos, environment, access and child_count.

json
{
  "id":"3127593", "title":"Museo Nacional del Prado",
  "node_type":"Attractions", "rating":4.7,
  "rating_votes":131173, "address_city":"Madrid",
  "location":{"lat":40.4137818,"lon":-3.6921271},
  "url":"https://www.museodelprado.es/"
}

Other responses

search_venues and list_subareas response examples are not documented yet. Their input schemas are documented; check real responses before relying on specific fields. They may follow a paginated-list pattern; check actual results before writing strict parsers.

Place Score in results

place_score is returned in listing items and detailed venue records. The sample payloads above were captured before Place Score was added, so they do not include it.

Pagination rules

  • Treat cursors as opaque; do not decode or generate them.
  • find_venues and search_venues allow limit 1–50; list_subareas allows 1–100; resolve_place allows 1–10.
  • Keep the same filters, geographic scope and sort order when using next_cursor.
  • A page with count: 15 and has_more: true is not a scoped global total.