Time Out APItimeout.com ↗
Access Time Out city guides, events, restaurants, attractions, hotels, and more across major global cities via a structured JSON API with 20 endpoints.
What is the Time Out API?
The Time Out API exposes 20 endpoints covering city guides, events, restaurants, attractions, hotels, and more from timeout.com. You can fetch curated listings by city slug, pull full detail pages for individual venues and events, or use the search endpoint to query content within a specific city. Response objects consistently include title, URL, image, and optional description fields, with detail endpoints adding address, telephone, price range, and publication metadata.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/b02aa18a-00d0-4b4c-819e-655fc4ec8cae/get_cities' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace timeout-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""
Time Out API - Usage Example
Get your API key from: https://parse.bot/settings
"""
from parse_apis.time_out_api import TimeOut, City_, PageNotFound
client = TimeOut()
# List all covered cities
for city in client.cities.list(limit=5):
print(city.name, city.slug)
# Construct a city and browse its restaurants
london = client.city(slug=City_.LONDON)
for listing in london.restaurants(limit=5):
print(listing.title, listing.url)
# Get today's top picks and drill into the first one
pick = london.whats_on_today(limit=1).first()
if pick:
detail = pick.detail()
print(detail.name, detail.city, detail.description[:100] if detail.description else "")
# Read a full article with embedded venue items
article = client.articles.get(url="https://www.timeout.com/london/restaurants/best-restaurants-in-london")
print(article.title, article.author)
for item in (article.items or [])[:3]:
print(item.name, item.url)
# Search within a city
for result in london.search(query="pizza", limit=3):
print(result.title, result.url)
# Typed error handling for a missing page
try:
client.venuedetails.get(url="https://www.timeout.com/london/things-to-do/nonexistent-page-12345")
except PageNotFound as exc:
print(f"Page not found: {exc.url}")
print("exercised: cities.list / city.restaurants / city.whats_on_today / listing.detail / articles.get / city.search / venuedetails.get")
Returns the curated list of 10 major cities covered by Time Out with their slugs and URLs. The site covers additional cities beyond this list.
No input parameters required.
{
"type": "object",
"fields": {
"cities": "array of city objects each with name, slug, and url"
},
"sample": {
"data": {
"cities": [
{
"url": "https://www.timeout.com/london",
"name": "London",
"slug": "london"
},
{
"url": "https://www.timeout.com/newyork",
"name": "New York",
"slug": "newyork"
},
{
"url": "https://www.timeout.com/paris",
"name": "Paris",
"slug": "paris"
}
]
},
"status": "success"
}
}About the Time Out API
City Coverage and Listings
The get_cities endpoint returns a curated list of 10 major cities — London, New York, Paris, Chicago, Los Angeles, Miami, Barcelona, Tokyo, Singapore, and Dubai — each with a name, slug, and url. These slugs feed directly into the city parameter across all category endpoints. The get_city_homepage endpoint returns featured editorial picks and promoted deals for a given city. Coverage depth varies significantly by city: London and New York have the broadest data, while cities like Paris or Tokyo may return empty listings on certain category endpoints such as get_things_to_do or get_attractions.
Events, Culture, and Entertainment
Event-oriented endpoints include get_events, get_whats_on_today, get_kids_events, get_culture_events, get_music_events, and get_movies. Each returns a city, a fixed category string, and a listings array of objects with title, url, image, and optional description. For a single event page, get_event_detail accepts a full timeout.com URL and returns name, address, image, description, and city. Culture and kids event coverage is strongest for London and Chicago; New York and other cities may return empty arrays for those categories.
Food, Dining, and Venues
The get_restaurants, get_food_and_drink, and get_new_restaurant_openings endpoints provide restaurant recommendations and editorial food content. get_restaurant_detail accepts a full restaurant URL and returns name, description, address, telephone, and priceRange (the latter two may be null). New restaurant openings coverage is confirmed for London only — other cities may return an upstream error if no matching article is found. The get_time_out_market endpoint, which takes no inputs, returns a list of Time Out Market locations worldwide with title, url, and image.
Articles, Guides, and Search
The get_article_detail endpoint fetches a full article by URL, returning title, author, datePublished (ISO format), description (body text), and an items array of embedded venue objects with name, url, and image. get_city_guide_articles provides editorial travel content such as day trips, walks, and accommodation guides. The search endpoint accepts a city slug and a required query string, returning matched results from that city's content as an array of objects with title, url, image, and optional description.
The Time Out API is a managed, monitored endpoint for timeout.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when timeout.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official timeout.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a city activity planner that aggregates daily listings from
get_whats_on_todayfor multiple cities. - Enrich a travel app with restaurant details — including address, telephone, and price range — via
get_restaurant_detail. - Populate an event discovery feed with categorized listings from
get_music_eventsandget_culture_events. - Create a family travel guide by filtering
get_kids_eventsresults for London and Chicago. - Monitor new restaurant openings in London using
get_new_restaurant_openingsfor food industry tracking. - Integrate Time Out Market location data via
get_time_out_marketinto a global food hall directory. - Supplement a city guide app with editorial articles and embedded venue lists from
get_article_detail.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Time Out have an official developer API?+
What does `get_event_detail` return compared to the listing endpoints?+
get_events return lightweight objects with title, url, image, and optional description. get_event_detail accepts a full timeout.com URL and returns the full page data: name, description, address (as an object or null), image, and city. It is the only event endpoint that exposes address-level data.Which cities have the most reliable data coverage across endpoints?+
get_whats_on_today, get_kids_events, and get_things_to_do. Paris, Tokyo, Dubai, and Singapore may return empty listings on several category endpoints due to lower editorial coverage on the source site.Does the API support pagination or return all listings in a single response?+
page or offset parameter available on any endpoint. If you need deeper pagination into category listings, you can fork this API on Parse and revise the relevant endpoints to add pagination support.Does the API expose user reviews or ratings for restaurants and venues?+
get_restaurant_detail and get_event_detail return editorial descriptions, address, and price range, but do not include user review text or aggregate ratings. You can fork this API on Parse and revise it to add a reviews endpoint if that data is available on the source pages.