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

# API

> API reference for Foursquare: every `foursquare.api.*` operation with input and output types.

Every `foursquare.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Places

### autocomplete

`places.autocomplete`

Suggest places, searches or geos for a partial query

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.autocomplete({ query: 'sta', ll: '41.8781,-87.6298' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | At least 3 characters |
| `ll` | `string` | No | — |
| `radius` | `number` | No | — |
| `types` | `(place \| search \| geo)[]` | No | Any combination of result types |
| `bias` | `place \| search \| geo` | No | Prefer one result type |
| `session_token` | `string` | No | Groups a query with the selection it leads to |
| `limit` | `number` | No | — |

`query` must be at least 3 characters. This endpoint takes `ll` for a location; unlike Place Search it has no `near` parameter, so a locality name cannot bias it. `types` and `bias` accept place, search or geo. Each result carries a `type` and a `text`. A place result nests the whole place under `place`, so its id is `result.place.fsq_place_id`; a geo or search result has no `place`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   type: string,
>   text?: {
>     primary?: string | null,
>     secondary?: string | null,
>     highlight?: {
>       start?: number | null,
>       length?: number | null
>     }[] | null
>   } | null,
>   link?: string | null,
>   place?: {
>     fsq_place_id: string,
>     name?: string | null,
>     latitude?: number | null,
>     longitude?: number | null,
>     distance?: number | null,
>     categories?: {
>       fsq_category_id?: string | null,
>       name?: string | null,
>       short_name?: string | null,
>       plural_name?: string | null,
>       icon?: {
>         id?: string | null,
>         prefix?: string | null,
>         suffix?: string | null,
>         width?: number | null,
>         height?: number | null
>       } | null
>     }[] | null,
>     chains?: {
>       fsq_chain_id?: string | null,
>       name?: string | null
>     }[] | null,
>     location?: {
>       address?: string | null,
>       locality?: string | null,
>       region?: string | null,
>       postcode?: string | null,
>       country?: string | null,
>       admin_region?: string | null,
>       post_town?: string | null,
>       po_box?: string | null,
>       formatted_address?: string | null
>     } | null,
>     tel?: string | null,
>     email?: string | null,
>     website?: string | null,
>     social_media?: {
>       facebook_id?: string | null,
>       instagram?: string | null,
>       twitter?: string | null
>     } | null,
>     link?: string | null,
>     description?: string | null,
>     price?: number | null,
>     rating?: number | null,
>     popularity?: number | null,
>     stats?: {
>       total_photos?: number | null,
>       total_ratings?: number | null,
>       total_tips?: number | null
>     } | null,
>     related_places?: {
>       parent?: Record<string, any> | null,
>       children?: Record<string, any>[] | null
>     } | null,
>     hours?: {
>       display?: string | null,
>       is_local_holiday?: boolean | null,
>       open_now?: boolean | null,
>       regular?: Record<string, any>[] | null
>     } | null,
>     extended_location?: {
>       dma?: string | null,
>       census_block_id?: string | null
>     } | null,
>     date_created?: string | null,
>     date_refreshed?: string | null,
>     date_closed?: string | null,
>     placemaker_url?: string | null,
>     store_id?: string | null,
>     tastes?: string[] | null,
>     menu?: string | null,
>     attributes?: Record<string, any> | null,
>     veracity_rating?: Record<string, any> | null,
>     unresolved_flags?: string[] | null
>   } | null
> }[]
> ```

***

### get

`places.get`

Get one place by its fsq\_place\_id, with all its details

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.get({ fsq_place_id: '4b28f2aef964a520f9d024e3' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `fsq_place_id` | `string` | Yes | — |
| `fields` | `string[]` | No | — |

Answers the place object directly, not wrapped. `fields` narrows it; omitting it returns every Pro field.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `fsq_place_id` | `string` | Yes | The place id used by every other call |
| `name` | `string \| null` | No | — |
| `latitude` | `number \| null` | No | — |
| `longitude` | `number \| null` | No | — |
| `distance` | `number \| null` | No | Metres from the search location; Place Search only |
| `categories` | `object[] \| null` | No | — |
| `chains` | `object[] \| null` | No | — |
| `location` | `object \| null` | No | — |
| `tel` | `string \| null` | No | — |
| `email` | `string \| null` | No | — |
| `website` | `string \| null` | No | — |
| `social_media` | `object \| null` | No | — |
| `link` | `string \| null` | No | The Place Details URL for this place |
| `description` | `string \| null` | No | — |
| `price` | `number \| null` | No | 1 to 4 |
| `rating` | `number \| null` | No | 0.0 to 10.0 |
| `popularity` | `number \| null` | No | — |
| `stats` | `object \| null` | No | — |
| `related_places` | `object \| null` | No | — |
| `hours` | `object \| null` | No | — |
| `extended_location` | `object \| null` | No | — |
| `date_created` | `string \| null` | No | — |
| `date_refreshed` | `string \| null` | No | — |
| `date_closed` | `string \| null` | No | — |
| `placemaker_url` | `string \| null` | No | — |
| `store_id` | `string \| null` | No | — |
| `tastes` | `string[] \| null` | No | — |
| `menu` | `string \| null` | No | — |
| `attributes` | `Record<string, any> \| null` | No | — |
| `veracity_rating` | `Record<string, any> \| null` | No | — |
| `unresolved_flags` | `string[] \| null` | No | — |

> [accordion] categories full type
>
> ```ts theme={null}
> {
>   fsq_category_id?: string | null,
>   name?: string | null,
>   short_name?: string | null,
>   plural_name?: string | null,
>   icon?: {
>     id?: string | null,
>     prefix?: string | null,
>     suffix?: string | null,
>     width?: number | null,
>     height?: number | null
>   } | null
> }[] | null
> ```

> [accordion] chains full type
>
> ```ts theme={null}
> {
>   fsq_chain_id?: string | null,
>   name?: string | null
> }[] | null
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   address?: string | null,
>   locality?: string | null,
>   region?: string | null,
>   postcode?: string | null,
>   country?: string | null,
>   admin_region?: string | null,
>   post_town?: string | null,
>   po_box?: string | null,
>   formatted_address?: string | null
> } | null
> ```

> [accordion] social\_media full type
>
> ```ts theme={null}
> {
>   facebook_id?: string | null,
>   instagram?: string | null,
>   twitter?: string | null
> } | null
> ```

> [accordion] stats full type
>
> ```ts theme={null}
> {
>   total_photos?: number | null,
>   total_ratings?: number | null,
>   total_tips?: number | null
> } | null
> ```

> [accordion] related\_places full type
>
> ```ts theme={null}
> {
>   parent?: Record<string, any> | null,
>   children?: Record<string, any>[] | null
> } | null
> ```

> [accordion] hours full type
>
> ```ts theme={null}
> {
>   display?: string | null,
>   is_local_holiday?: boolean | null,
>   open_now?: boolean | null,
>   regular?: Record<string, any>[] | null
> } | null
> ```

> [accordion] extended\_location full type
>
> ```ts theme={null}
> {
>   dma?: string | null,
>   census_block_id?: string | null
> } | null
> ```

***

### match

`places.match`

Resolve a name and address to a Foursquare place, with a match score

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.match({ name: 'Wrigley Field', address: '1060 W Addison St', city: 'Chicago', state: 'IL', cc: 'US' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Name of the place to match |
| `address` | `string` | Yes | Street address |
| `city` | `string` | Yes | — |
| `state` | `string` | No | — |
| `postal_code` | `string` | No | — |
| `cc` | `string` | Yes | 2-letter country code, e.g. US. Foursquare supports English-speaking countries only |
| `ll` | `string` | No | latitude,longitude |
| `fields` | `string[]` | No | — |

Answers `{ place, match_score, context }`. `match_score` runs from 0 to 1. `name`, `address`, `city` and `cc` are all required, and `cc` must be a 2-letter code; Foursquare supports English-speaking countries only. Its reference lists 422 `Unsupported country` for a code outside that set, and the call can also answer 404 `Match not found` or a 400 asking for `ll`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `place` | `object \| null` | No | — |
| `match_score` | `number \| null` | No | How confident the match is, from 0 to 1 |
| `context` | `Record<string, any> \| null` | No | — |

> [accordion] place full type
>
> ```ts theme={null}
> {
>   fsq_place_id: string,
>   name?: string | null,
>   latitude?: number | null,
>   longitude?: number | null,
>   distance?: number | null,
>   categories?: {
>     fsq_category_id?: string | null,
>     name?: string | null,
>     short_name?: string | null,
>     plural_name?: string | null,
>     icon?: {
>       id?: string | null,
>       prefix?: string | null,
>       suffix?: string | null,
>       width?: number | null,
>       height?: number | null
>     } | null
>   }[] | null,
>   chains?: {
>     fsq_chain_id?: string | null,
>     name?: string | null
>   }[] | null,
>   location?: {
>     address?: string | null,
>     locality?: string | null,
>     region?: string | null,
>     postcode?: string | null,
>     country?: string | null,
>     admin_region?: string | null,
>     post_town?: string | null,
>     po_box?: string | null,
>     formatted_address?: string | null
>   } | null,
>   tel?: string | null,
>   email?: string | null,
>   website?: string | null,
>   social_media?: {
>     facebook_id?: string | null,
>     instagram?: string | null,
>     twitter?: string | null
>   } | null,
>   link?: string | null,
>   description?: string | null,
>   price?: number | null,
>   rating?: number | null,
>   popularity?: number | null,
>   stats?: {
>     total_photos?: number | null,
>     total_ratings?: number | null,
>     total_tips?: number | null
>   } | null,
>   related_places?: {
>     parent?: Record<string, any> | null,
>     children?: Record<string, any>[] | null
>   } | null,
>   hours?: {
>     display?: string | null,
>     is_local_holiday?: boolean | null,
>     open_now?: boolean | null,
>     regular?: Record<string, any>[] | null
>   } | null,
>   extended_location?: {
>     dma?: string | null,
>     census_block_id?: string | null
>   } | null,
>   date_created?: string | null,
>   date_refreshed?: string | null,
>   date_closed?: string | null,
>   placemaker_url?: string | null,
>   store_id?: string | null,
>   tastes?: string[] | null,
>   menu?: string | null,
>   attributes?: Record<string, any> | null,
>   veracity_rating?: Record<string, any> | null,
>   unresolved_flags?: string[] | null
> } | null
> ```

***

### photos

`places.photos`

List the photos attached to a place

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.photos({ fsq_place_id: '4b28f2aef964a520f9d024e3', limit: 5 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `fsq_place_id` | `string` | Yes | — |
| `limit` | `number` | No | — |
| `sort` | `POPULAR \| NEWEST` | No | Defaults to POPULAR |
| `classifications` | `string[]` | No | Restrict to these photo classifications |

Returns `{ photos: [...] }`: Foursquare answers a bare array and the plugin wraps it. `sort` accepts POPULAR or NEWEST. Build an image URL by concatenating `prefix`, a size (32, 44, 64, 88, 120 or 512) and `suffix`, as in `{prefix}512{suffix}`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `photos` | `object[]` | Yes | — |

> [accordion] photos full type
>
> ```ts theme={null}
> {
>   id: string,
>   created_at?: string | null,
>   prefix: string,
>   suffix: string,
>   width?: number | null,
>   height?: number | null,
>   classifications?: string[] | null
> }[]
> ```

***

### search

`places.search`

Search the Foursquare places database by text, category or location

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.search({ query: 'coffee', near: 'Chicago, IL', limit: 10 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | No | Text to match against a place |
| `ll` | `string` | No | latitude,longitude, e.g. 41.8781,-87.6298 |
| `near` | `string` | No | A geocodable locality, e.g. Chicago, IL |
| `ne` | `string` | No | North-east corner of a rectangle |
| `sw` | `string` | No | South-west corner of a rectangle |
| `radius` | `number` | No | Metres; only with ll or ip bias. Default 22000 |
| `fsq_category_ids` | `string[]` | No | Category ids, comma-joined before sending |
| `fsq_chain_ids` | `string[]` | No | — |
| `exclude_fsq_chain_ids` | `string[]` | No | — |
| `exclude_all_chains` | `boolean` | No | — |
| `min_price` | `number` | No | — |
| `max_price` | `number` | No | — |
| `open_now` | `boolean` | No | — |
| `open_at` | `string` | No | A local day and time window |
| `sort` | `RELEVANCE \| RATING \| DISTANCE \| POPULARITY` | No | Defaults to RELEVANCE |
| `tel_format` | `NATIONAL \| E164` | No | Format of the returned telephone number |
| `fields` | `string[]` | No | Response fields; all Pro fields when omitted |
| `cursor` | `string` | No | Next-page cursor from a previous response. Omit it for the first page |
| `limit` | `number` | No | Results per page, max 50, default 10 |

Take a location as `ll` with an optional `radius`, as `near`, or as `ne` and `sw`. With none of them the search falls back to IP biasing. Array filters such as `fsq_category_ids` and `fields` are comma-joined before sending. `limit` caps at 50 and defaults to 10. Each response carries `nextCursor` when more results exist; pass it back as `cursor` to fetch the next page of the same search.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `context` | `object \| null` | No | — |
| `nextCursor` | `string \| null` | No | Pass this back as cursor to fetch the next page |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   fsq_place_id: string,
>   name?: string | null,
>   latitude?: number | null,
>   longitude?: number | null,
>   distance?: number | null,
>   categories?: {
>     fsq_category_id?: string | null,
>     name?: string | null,
>     short_name?: string | null,
>     plural_name?: string | null,
>     icon?: {
>       id?: string | null,
>       prefix?: string | null,
>       suffix?: string | null,
>       width?: number | null,
>       height?: number | null
>     } | null
>   }[] | null,
>   chains?: {
>     fsq_chain_id?: string | null,
>     name?: string | null
>   }[] | null,
>   location?: {
>     address?: string | null,
>     locality?: string | null,
>     region?: string | null,
>     postcode?: string | null,
>     country?: string | null,
>     admin_region?: string | null,
>     post_town?: string | null,
>     po_box?: string | null,
>     formatted_address?: string | null
>   } | null,
>   tel?: string | null,
>   email?: string | null,
>   website?: string | null,
>   social_media?: {
>     facebook_id?: string | null,
>     instagram?: string | null,
>     twitter?: string | null
>   } | null,
>   link?: string | null,
>   description?: string | null,
>   price?: number | null,
>   rating?: number | null,
>   popularity?: number | null,
>   stats?: {
>     total_photos?: number | null,
>     total_ratings?: number | null,
>     total_tips?: number | null
>   } | null,
>   related_places?: {
>     parent?: Record<string, any> | null,
>     children?: Record<string, any>[] | null
>   } | null,
>   hours?: {
>     display?: string | null,
>     is_local_holiday?: boolean | null,
>     open_now?: boolean | null,
>     regular?: Record<string, any>[] | null
>   } | null,
>   extended_location?: {
>     dma?: string | null,
>     census_block_id?: string | null
>   } | null,
>   date_created?: string | null,
>   date_refreshed?: string | null,
>   date_closed?: string | null,
>   placemaker_url?: string | null,
>   store_id?: string | null,
>   tastes?: string[] | null,
>   menu?: string | null,
>   attributes?: Record<string, any> | null,
>   veracity_rating?: Record<string, any> | null,
>   unresolved_flags?: string[] | null
> }[]
> ```

> [accordion] context full type
>
> ```ts theme={null}
> {
>   geo_bounds?: Record<string, any> | null
> } | null
> ```

***

### tips

`places.tips`

List the user tips left on a place

**Risk:** `read`

```ts theme={null}
await corsair.foursquare.api.places.tips({ fsq_place_id: '4b28f2aef964a520f9d024e3', sort: 'POPULAR', limit: 10 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `fsq_place_id` | `string` | Yes | — |
| `limit` | `number` | No | — |
| `sort` | `POPULAR \| NEWEST` | No | Defaults to POPULAR |
| `fields` | `string[]` | No | — |

Returns `{ tips: [...] }`: Foursquare answers a bare array and the plugin wraps it. A tip carries `fsq_tip_id`, `created_at` and `text` by default; ask for `agree_count`, `disagree_count`, `lang` or `url` through `fields`. `sort` accepts POPULAR or NEWEST.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tips` | `object[]` | Yes | — |

> [accordion] tips full type
>
> ```ts theme={null}
> {
>   fsq_tip_id: string,
>   created_at?: string | null,
>   text?: string | null,
>   url?: string | null,
>   lang?: string | null,
>   agree_count?: number | null,
>   disagree_count?: number | null
> }[]
> ```

***


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