Skip to main content
GET
Page through the places in a location that have posts in a date window, newest post first. Each place carries up to posts_per_place of its most recent eligible posts inline, so a coverage report needs one request per page rather than one request per place.
​
string
required
Bearer <your API key>. The X-Seekeasy-Key header still works, but is deprecated — responses to it carry a Warning header.

​
Choosing a location

Send at least one of metro, country, opentable_metro and opentable_country. A request carrying none of them is a 400. Several of them compose as a plain AND over the same places, in any combination. A combination that matches nothing — metro=nyc&country=GBR, say — is an empty page with total_count: 0, not an error.
metro and country are Seekeasy’s vocabularies; opentable_metro and opentable_country are OpenTable’s. They are not interchangeable, and they can disagree about the same venue. country takes ISO 3166-1 alpha-3 (USA), opentable_country takes alpha-2 (US).
The two OpenTable filters are served by our replica of OpenTable’s venue directory. A venue that has not yet reached the replica is excluded from both places and total_count, so prefer metro or country when you want every place we hold for a partner venue.
​
string
Seekeasy metropolitan area code, e.g. nyc, sf. See Metropolitan area codes for the full list. An unrecognized code is a 400 rather than an empty page.
​
string
ISO 3166-1 alpha-3 country code, e.g. USA, GBR. Matched case-insensitively against the country we geocoded each place to, so it reaches places that belong to no metropolitan area at all — a country=USA page can therefore be larger than the sum of the US metro pages. Places we have not geocoded to a country are excluded. Anything that is not three letters is a 400, which is what stops the alpha-2 US from silently returning an empty page.
​
string
OpenTable’s own metro name for the venue, e.g. West Palm Beach. Matched exactly, against the value OpenTable files the venue under, so it is never approximated onto a Seekeasy metro. OpenTable’s metros are a finer grain than ours in places — it files West Palm Beach and Fort Lauderdale separately where metro=mia covers both — and a coarser one in others, e.g. España.
​
string
OpenTable’s own country code for the venue, ISO 3166-1 alpha-2, e.g. US, GB. Matched case-insensitively. Anything that is not two letters is a 400.

​
Choosing a date window

​
string
required
Start of the window in MM-DD-YYYY format, inclusive. Only posts created at or after midnight UTC on that date are considered, both for which places appear and for the posts returned with them.
​
string
End of the window in MM-DD-YYYY format, exclusive. Must be after posts_newer_than, or the request is a 400.

​
Paging and post filters

​
integer
default:"20"
Number of places to return, 1–50.
​
integer
default:"0"
Number of places to skip. A page past the end of the match set is an empty places array with the real total_count.
​
integer
default:"5"
Maximum number of posts returned with each place, 1–20. This caps the posts, not the places, and it does not affect total_video_count.
​
string
Only include posts whose dominant language is this ISO 639-1 short code, e.g. en, es.
​
integer
Only include posts whose videos are smaller than this size in bytes.
​
integer
Only include posts whose images are smaller than this size in bytes.
​
number
Only include posts whose videos are shorter than this duration.
​
boolean
Only include posts whose audio can be played unmuted.
Don’t hold the response. The signed media URLs expire one hour after the call.

​
Response Fields

​
array
The requested page of places, ordered by their newest eligible post.
​
integer
How many places match the request, before limit and offset are applied. It counts places, not posts.
​
integer
How many eligible video posts there are across every matching place, before limit, offset and posts_per_place are applied. It counts posts, not places, and respects the same date window and post filters as the page. A post counts as a video when its first media item is one, and a post tagged at several matching places counts once, so this can be less than the sum over places.
​
integer
The limit this page was built with.
​
integer
The offset this page was built with.
Each entry in places carries the same fields as Place Lookup — place_id, slate_id, place_name, address, tagline, highlights, coordinates, seekeasy_url, is_trending, is_creator_fav and posts.

​
Metropolitan area codes

metro takes one of these 105 codes. The country column is the country each metro belongs to, which is not the same test as country: country reads the geocode of each individual place, so a place filed under a US metro whose own geocode says otherwise is in metro=nyc but not in country=USA.

​
United States — 66 metros

​
Rest of world — 39 metros