> ## Documentation Index
> Fetch the complete documentation index at: https://seekeasy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Places List

> GET /v1/places - Page through the places in a location with their newest social content

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.

<ParamField header="Authorization" type="string" required>
  `Bearer <your API key>`. The `X-Seekeasy-Key` header still works, but is deprecated — responses to
  it carry a `Warning` header.
</ParamField>

## 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.

<Note>
  `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`).
</Note>

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.

<ParamField query="metro" type="string">
  Seekeasy metropolitan area code, e.g. `nyc`, `sf`. See [Metropolitan area codes](#metropolitan-area-codes) for the full list. An unrecognized code is a `400` rather than an empty page.
</ParamField>

<ParamField query="country" type="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.
</ParamField>

<ParamField query="opentable_metro" type="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`.
</ParamField>

<ParamField query="opentable_country" type="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`.
</ParamField>

## Choosing a date window

<ParamField query="posts_newer_than" type="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.
</ParamField>

<ParamField query="posts_older_than" type="string">
  End of the window in `MM-DD-YYYY` format, exclusive. Must be after `posts_newer_than`, or the request is a `400`.
</ParamField>

## Paging and post filters

<ParamField query="limit" type="integer" default="20">
  Number of places to return, 1–50.
</ParamField>

<ParamField query="offset" type="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`.
</ParamField>

<ParamField query="posts_per_place" type="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`.
</ParamField>

<ParamField query="language_short_code" type="string">
  Only include posts whose dominant language is this ISO 639-1 short code, e.g. `en`, `es`.
</ParamField>

<ParamField query="max_video_size_bytes" type="integer">
  Only include posts whose videos are smaller than this size in bytes.
</ParamField>

<ParamField query="max_image_size_bytes" type="integer">
  Only include posts whose images are smaller than this size in bytes.
</ParamField>

<ParamField query="max_video_duration_seconds" type="number">
  Only include posts whose videos are shorter than this duration.
</ParamField>

<ParamField query="playable_audio" type="boolean">
  Only include posts whose audio can be played unmuted.
</ParamField>

<Warning>
  **Don't hold the response.** The signed media URLs expire one hour after the call.
</Warning>

## Response Fields

<ResponseField name="places" type="array">
  The requested page of places, ordered by their newest eligible post.
</ResponseField>

<ResponseField name="total_count" type="integer">
  How many **places** match the request, before `limit` and `offset` are applied. It counts places, not posts.
</ResponseField>

<ResponseField name="total_video_count" type="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.
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` this page was built with.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` this page was built with.
</ResponseField>

Each entry in `places` carries the same fields as [Place Lookup](/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

| Code | Metropolitan area |
| - | - |
| `nyc` | New York City |
| `li` | Long Island |
| `nj` | New Jersey |
| `hv` | Hudson Valley |
| `la` | Los Angeles |
| `chi` | Chicago |
| `dfw` | Dallas-Fort Worth |
| `hou` | Houston |
| `dc` | Washington, D.C. |
| `phi` | Philadelphia |
| `atl` | Atlanta |
| `mia` | Miami |
| `det` | Detroit |
| `sd` | San Diego |
| `phx` | Phoenix |
| `bos` | Boston |
| `ie` | Inland Empire |
| `sf` | San Francisco |
| `sea` | Seattle |
| `msp` | Minneapolis-St. Paul |
| `tb` | Tampa Bay |
| `den` | Denver |
| `bal` | Baltimore |
| `stl` | St. Louis |
| `orl` | Orlando |
| `clt` | Charlotte |
| `sa` | San Antonio |
| `pdx` | Portland |
| `pit` | Pittsburgh |
| `aus` | Austin |
| `sac` | Sacramento |
| `lv` | Las Vegas |
| `cin` | Cincinnati |
| `kc` | Kansas City |
| `col` | Columbus |
| `cle` | Cleveland |
| `ind` | Indianapolis |
| `nas` | Nashville |
| `vb` | Virginia Beach-Norfolk |
| `jax` | Jacksonville |
| `okc` | Oklahoma City |
| `ral` | Raleigh |
| `mem` | Memphis |
| `lou` | Louisville |
| `ric` | Richmond |
| `nola` | New Orleans |
| `slc` | Salt Lake City |
| `htf` | Hartford |
| `buf` | Buffalo |
| `bhm` | Birmingham |
| `roc` | Rochester |
| `mil` | Milwaukee |
| `chs` | Charleston |
| `sav` | Savannah |
| `hnl` | Honolulu |
| `tus` | Tucson |
| `abq` | Albuquerque |
| `btr` | Baton Rouge |
| `oma` | Omaha |
| `dsm` | Des Moines |
| `boi` | Boise |
| `grr` | Grand Rapids |
| `tul` | Tulsa |
| `gso` | Greensboro |
| `elp` | El Paso |
| `anc` | Anchorage |

### Rest of world — 39 metros

| Code | Metropolitan area | Country |
| - | - | - |
| `london` | London | GBR |
| `manchester` | Manchester | GBR |
| `edinburgh` | Edinburgh | GBR |
| `glasgow` | Glasgow | GBR |
| `dublin` | Dublin | IRL |
| `toronto` | Toronto | CAN |
| `vancouver` | Vancouver | CAN |
| `montreal` | Montreal | CAN |
| `ottawa` | Ottawa | CAN |
| `calgary` | Calgary | CAN |
| `sydney` | Sydney | AUS |
| `melbourne` | Melbourne | AUS |
| `adelaide` | Adelaide | AUS |
| `brisbane` | Brisbane | AUS |
| `perth` | Perth | AUS |
| `paris` | Paris | FRA |
| `tokyo` | Tokyo | JPN |
| `osaka` | Osaka | JPN |
| `kyoto` | Kyoto | JPN |
| `mexico-city` | Mexico City | MEX |
| `guadalajara` | Guadalajara | MEX |
| `monterrey` | Monterrey | MEX |
| `cancun` | Cancun | MEX |
| `barcelona` | Barcelona | ESP |
| `madrid` | Madrid | ESP |
| `seoul` | Seoul | KOR |
| `singapore` | Singapore | SGP |
| `berlin` | Berlin | DEU |
| `munich` | Munich | DEU |
| `hamburg` | Hamburg | DEU |
| `frankfurt` | Frankfurt | DEU |
| `amsterdam` | Amsterdam | NLD |
| `dubai` | Dubai | ARE |
| `rome` | Rome | ITA |
| `milan` | Milan | ITA |
| `bangkok` | Bangkok | THA |
| `hong-kong` | Hong Kong | HKG |
| `lisbon` | Lisbon | PRT |
| `taipei` | Taipei | TWN |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.seekeasy.ai/v1/places?metro=nyc&posts_newer_than=01-01-2025&limit=20" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.seekeasy.ai/v1/places",
      params={
          "country": "USA",
          "posts_newer_than": "01-01-2025",
          "limit": 20,
          "posts_per_place": 3,
      },
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    opentable_metro: "West Palm Beach",
    posts_newer_than: "01-01-2025",
    limit: "20",
  });
  const response = await fetch(`https://api.seekeasy.ai/v1/places?${params}`, {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "places": [
      {
        "place_id": "8a283082c2dffff:Tartine Bakery",
        "slate_id": "b1f0c2d4-9e3a-4c17-8f2b-5a6d7e8f9012",
        "place_name": "Tartine Bakery",
        "address": "600 Guerrero St, San Francisco, CA 94110",
        "tagline": "Iconic bakery known for morning buns and country bread",
        "highlights": ["Famous morning buns", "Country sourdough"],
        "coordinates": {
          "lat": 37.7614,
          "lon": -122.4241
        },
        "seekeasy_url": null,
        "is_trending": true,
        "is_creator_fav": true,
        "posts": [
          {
            "post_id": "post_xyz789",
            "media": [
              {
                "video_url": null,
                "video_duration_seconds": null,
                "video_file_size_bytes": null,
                "image_url": "https://cdn.seekeasy.ai/media/posts/post_xyz789_cover600x744.jpg",
                "poster_image_url": null,
                "is_video": false
              }
            ],
            "caption": "The morning bun at Tartine is unreal",
            "source_url": "https://www.instagram.com/p/XYZ789",
            "instagram_shortcode": "XYZ789",
            "tiktok_video_id": null,
            "created_on": "2025-03-01T00:00:00+00:00",
            "source_type": "instagram",
            "should_mute_audio": false,
            "profile": {
              "profile_id": "sf_foodie_anna",
              "avatar_url": "https://cdn.seekeasy.ai/media/profiles/sf_foodie_anna_avatar200.jpg",
              "instagram_username": "sf_foodie_anna",
              "instagram_follower_count": 45200,
              "instagram_post_count": 812,
              "tiktok_username": null,
              "tiktok_follower_count": null,
              "tiktok_post_count": null,
              "place_count": 143,
              "taste_profile": ["bakeries", "brunch spots"]
            }
          }
        ]
      }
    ],
    "total_count": 214,
    "total_video_count": 1873,
    "limit": 20,
    "offset": 0
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "At least one of metro, country, opentable_metro and opentable_country is required"
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "country must be an ISO 3166-1 alpha-3 code (e.g. 'USA'): US"
  }
  ```

  ```json 403 theme={null}
  {
    "detail": "API key is not authorized for this endpoint"
  }
  ```

  ```json 503 theme={null}
  {
    "detail": "The places query timed out; narrow the location or retry later"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.