Num places

Find real, currently-operating places in a destination — restaurants, bars, beaches, spas, viewpoints, temples. Ranked by quality (rating weighted by how many reviews stand behind it). When `near` is a "lat,lng" coordinate pair, results are limited to about 5 km of that point, ranked by a blend of quality and distance — so a 4.8★ institution two streets away beats an unrated snack bar next door — and each carries `distance_m`. When `near` is a neighbourhood name it filters by area and NO distance is returned. Returns name, category, area, rating, review count, phone, address and opening hours where known. NEVER invents a place: if Num does not hold it, it is not returned. You MUST display the returned `attribution` string wherever you show these results.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Destination slug or city name, e.g. \"phuket\", \"bangkok\"."
    },
    "category": {
      "type": "string",
      "description": "restaurant | bar | beach | spa | viewpoint | temple | waterfall | cafe (any case). Omit for all."
    },
    "near": {
      "type": "string",
      "description": "A \"lat,lng\" pair (e.g. \"7.8208,98.2976\") for distance-ranked results, or a neighbourhood name to filter by area, e.g. \"Kata Beach\"."
    },
    "query": {
      "type": "string",
      "description": "Free text, e.g. \"thai seafood\", \"rooftop\"."
    },
    "limit": {
      "type": "integer",
      "description": "Max results, 1–20. Default 8."
    }
  },
  "required": [
    "destination"
  ]
}

Ask Num the way a traveller would — "where should we eat tonight near Kata?", "which beach for sunset?" — and get a short concierge answer grounded in Num's verified directory, plus the places it names as structured data so you can render your own cards. This is the whole product in one tool. It answers about the place asked and NEVER substitutes a different city. If Num has no coverage there it says so rather than guessing. It does not book, charge, or take personal details — send none. You MUST display the returned `attribution`.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The traveller's question, in their own words. Any language."
    },
    "destination": {
      "type": "string",
      "description": "Where they are, if you know it. Improves grounding."
    },
    "near": {
      "type": "string",
      "description": "Neighbourhood or hotel area, if known."
    },
    "language": {
      "type": "string",
      "description": "BCP-47 tag for the reply, e.g. \"th\", \"ru\". Defaults to the language of the question."
    }
  },
  "required": [
    "question"
  ]
}

Which destinations Num covers, with the number of verified places in each. Call this FIRST when you do not know whether a city is supported — it is cheaper than a failed search and stops you promising a traveller coverage that does not exist. Coverage is honest: a destination appears here only when it has a real, maintained directory.

{
  "type": "object",
  "properties": {}
}

Everything Num holds on one place, by place_id from search_places: contact details, hours, rating, review count, area, category, cuisine, the venue's own short description (`about`), coordinates, `open_now` computed in the destination's timezone (true / false / null — null means Num has not verified the hours, NOT that it is closed), the booking platform and — only where a verified owner chose it — the venue's own booking page, a recently-read published price line where Num holds one, and up to 8 approved member photos plus the listing photo, each with its own `attribution` you MUST show alongside it. Use before showing a detail page or handing a traveller a phone number. Returns only what is verified — absent fields are absent because Num does not know them, never because they were omitted for brevity. Do not fill gaps from memory; an invented phone number is worse than a missing one.

{
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "From search_places."
    }
  },
  "required": [
    "place_id"
  ]
}

Places that are OPEN RIGHT NOW in a destination, computed in the destination's own timezone. Businesses whose own website is a dead domain or a 404 are excluded entirely — they have closed down. IMPORTANT: only venues whose opening hours Num has verified can appear here, so a short list means thin hours coverage, NOT an empty city. Never tell a traveller "nothing is open" on the strength of this tool; say that these are the ones Num can confirm are open. Use search_places for the full directory.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Destination slug, e.g. \"los-angeles\"."
    },
    "category": {
      "type": "string",
      "description": "Exact category, e.g. \"Restaurant\". Omit for all."
    },
    "near": {
      "type": "string",
      "description": "Neighbourhood, e.g. \"Silver Lake\"."
    },
    "bookable_only": {
      "type": "boolean",
      "description": "Only venues Num can hand off a booking page for."
    },
    "limit": {
      "type": "integer",
      "description": "Max results, 1–50. Default 20."
    }
  },
  "required": [
    "destination"
  ]
}

A booking page for one place with the party size, date and time ALREADY FILLED IN. This does NOT make a reservation and Num does not hold a table — the traveller completes it on the venue's own platform (OpenTable, Resy, Tock, SevenRooms, Square and others). The response always carries `booked: false` and `mode: "deeplink"`. You MUST NOT render this as a confirmation, and you MUST NOT tell a traveller a table is held. If the venue has no booking platform the response says so and returns the phone number instead — offer that rather than implying it cannot be visited.

{
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "From search_places or open_places."
    },
    "party": {
      "type": "integer",
      "description": "Number of covers, 1–20."
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD."
    },
    "time": {
      "type": "string",
      "description": "HH:MM, 24-hour, local to the venue."
    }
  },
  "required": [
    "place_id"
  ]
}

The venue's own published menu or list of offerings — dishes, treatments, tours — grouped by the venue's sections in the venue's order. Free: included in the no-fee free tier, no key needed to try it. Written by the venue itself in its Num dashboard, not scraped: prices are exactly as the venue set them, in its own currency, each with the formatted amount, the currency code and the integer minor units. A price is what the venue says it charges, NOT a quote — never tell a traveller their bill will be that figure. An item with no price has `price: null` (or only a note such as "market price"); do not estimate one. If the venue has not published a menu, `sections` is empty and `note` says so — say that, never invent dishes. Age-restricted items are never shown on this surface. You MUST display the returned `attribution`.

{
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "From search_places, place_details or directory_feed."
    }
  },
  "required": [
    "place_id"
  ]
}

A rating SUMMARY for one place, free (included in the no-fee free tier) — no review text and no reviewer identities, ever. Returns `external` (the public rating and review count the listing carries, with `source`, the site it was read from) and `num_verified`: the average, count and 1–5 star distribution of ratings from verified guests — people who booked through Num and checked in at the venue by scanning its own code. Guests the venue comped or worked with are excluded, and Num publishes no verified average until a place has 5 such ratings (below that every number is null and `note` says why). Keep the two numbers separate; do not average them together. You MUST display the returned `attribution`.

{
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "From search_places, place_details or directory_feed."
    }
  },
  "required": [
    "place_id"
  ]
}

Bulk, paged sync of every place Num lists in one destination — free (included in the no-fee free tier; one call returns up to 200 places), for keeping your own copy of the directory current instead of searching it call by call. Ordered by place_id; pass the returned `next_cursor` back as `cursor` until it is null. Each item has the search_places fields plus cuisine, lat, lng and booking_platform. Places Num has positive evidence have closed are excluded; `trading: null` means not yet checked, NOT closed. Contains no menus, reviews or photos — call get_menu, get_reviews or place_details for those. You MUST display the returned `attribution` wherever the data is shown.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "Destination slug from list_destinations, e.g. \"los-angeles\"."
    },
    "cursor": {
      "type": "string",
      "description": "The `next_cursor` from the previous page. Omit for the first page."
    },
    "limit": {
      "type": "integer",
      "description": "Places per page: 1–200 with an X-Partner-Key (default 100); without a key, at most 50."
    }
  },
  "required": [
    "destination"
  ]
}