NUM

Search NUM's travel directory: more than 2.5 million places — restaurants, bars, hotels, spas, tours and shops, deepest in Thailand and the UK. Say where to look: city (one of NUM's destinations — see num_list_destinations) or country; then narrow with q, area and category. Places NUM knows have closed are never returned. Returns name, category, address, phone, website, coordinates and whether the owner has claimed the listing; call num_get_place for how to book one. Each call counts against the daily read quota.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "A NUM destination, e.g. 'Phuket', 'Edinburgh', 'Bangkok', 'London'. Required unless country is given."
    },
    "country": {
      "type": "string",
      "description": "ISO-2 code or name, e.g. 'TH' or 'Thailand'. Searches every NUM destination in that country."
    },
    "area": {
      "type": "string",
      "description": "A neighbourhood inside the destination, e.g. 'Kata' or 'Soho'."
    },
    "q": {
      "type": "string",
      "description": "Free text matched against the place name."
    },
    "category": {
      "type": "string",
      "description": "e.g. 'Restaurant', 'Bar', 'Hotel', 'Spa', 'Tour'."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max results, default 20, cap 50."
    }
  }
}

Every destination NUM covers, with its country. Use a destination's name or slug as num_search_places city. Free, unmetered, and needs no key.

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

Full record for one place, by the place_id that num_search_places returned, including HOW TO BOOK IT on the venue's own terms. `booking.method` is one of: request (the venue takes requests through NUM and confirms each one itself), venue_system (send the traveller to booking.url, prefilled when you pass party_size, date and time), phone (the number is for the traveller to call), not_through_num, closed, unknown. Follow booking.guidance exactly. If open_status.closed is true, NUM holds evidence the place has gone: do not send anyone there. accolades carry their source; menu is the owner's own list and prices. Each call counts against the daily read quota.

{
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "The place_id returned by num_search_places."
    },
    "party_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "description": "Optional: people in the party, to prefill the venue's booking page."
    },
    "date": {
      "type": "string",
      "description": "Optional: YYYY-MM-DD, to prefill the venue's booking page."
    },
    "time": {
      "type": "string",
      "description": "Optional: HH:MM 24-hour, local to the venue."
    }
  },
  "required": [
    "place_id"
  ]
}

Submit a business to NUM for review. Free and unmetered. A person at 5arz reviews every submission before any traveller sees it, so the result is status 'pending_review', never an immediate listing. 'relationship' records whether the submitter owns the business, was engaged by the owner, or is a third party; reviewers verify it. Contact details must be ones the business has published — submissions with guessed or derived contact details are rejected. Re-sending the same external_ref updates the pending submission instead of creating a duplicate.

{
  "type": "object",
  "properties": {
    "relationship": {
      "type": "string",
      "enum": [
        "owner",
        "authorized_agent",
        "third_party"
      ],
      "description": "'owner' if you run it, 'authorized_agent' if the owner engaged you, 'third_party' if you neither own nor represent it."
    },
    "external_ref": {
      "type": "string",
      "description": "Your own reference for this business. Re-sending it edits the pending submission instead of creating a duplicate."
    },
    "name": {
      "type": "string",
      "description": "Trading name as it appears on the door."
    },
    "vertical": {
      "type": "string",
      "description": "restaurant, cafe, bar, hotel, spa, boat, tour, shop, transport, clinic, gym, attraction, other…"
    },
    "country": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "description": "Only if the business has published it. Do not derive it from the domain name."
    },
    "website": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "price_range": {
      "type": "string"
    },
    "hours": {
      "type": "string"
    },
    "callback_url": {
      "type": "string",
      "description": "NUM POSTs the review decision here."
    }
  },
  "required": [
    "relationship",
    "name",
    "country",
    "city"
  ]
}

Attach a promotion, special, event or ad to a business previously submitted by the same account. Free and unmetered. A person reviews it before it is shown to anyone. Re-sending the same promo_ref updates the pending promotion instead of creating a duplicate.

{
  "type": "object",
  "properties": {
    "submission_id": {
      "type": "string",
      "description": "From num_submit_business."
    },
    "external_ref": {
      "type": "string",
      "description": "Alternative to submission_id: the reference you used for the business."
    },
    "promo_ref": {
      "type": "string",
      "description": "Your own reference for this promotion, for idempotent edits."
    },
    "kind": {
      "type": "string",
      "enum": [
        "promo",
        "special",
        "event",
        "ad"
      ]
    },
    "title": {
      "type": "string",
      "description": "The single line a traveller reads."
    },
    "detail": {
      "type": "string"
    },
    "starts_at": {
      "type": "string",
      "description": "2026-08-01 or 2026-08-01T18:00:00Z."
    },
    "ends_at": {
      "type": "string"
    },
    "discount_pct": {
      "type": "integer",
      "minimum": 0,
      "maximum": 90
    },
    "terms": {
      "type": "string"
    }
  },
  "required": [
    "title"
  ]
}

Lists the businesses and promotions this account has submitted, with the reviewer's decision on each. Free and unmetered.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "approved",
        "rejected",
        "duplicate",
        "withdrawn"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  }
}