# Foursquare

> Search Foursquare for places, ask for recommendations in plain language, and pull a place's details, tips, and photos.

App · Travel & Places · 5 actions. Web page: https://docs.lodol.com/docs/integrations/foursquare

## Actions

### Ask for places

Ask Foursquare a question in plain language, such as 'best cocktail lounge in Williamsburg', and get back the places that answer it along with why each one matches.

**Inputs**

- Query (`query`, text, required): The question to answer, for example 'show me all cheap cafes in Williamsburg'.
- Location (`location`, text): A place to search in, such as 'Chicago, IL'. Needed unless the question already names one, or coordinates are given.
- Latitude, longitude (`ll`, text): Coordinates to search around, as 'latitude,longitude' (e.g. 41.8781,-87.6298). An alternative to naming a location.
- Context (`context`, text): Extra preferences to weigh, for example 'traveling with kids, need outdoor seating'.

**Outputs**

- `count` (number): Number of places returned.
- `places` (list): Places that answer the question.
- `summary` (text): Foursquare's written summary of the results, when it provides one.

**Example output**

```json
{
  "count": 1,
  "places": [
    {
      "address": "53 W Jackson Blvd, Chicago, IL 60604",
      "categories": [
        "Coffee Shop"
      ],
      "fsq_place_id": "4b6f0b40f964a520bce02ce3",
      "justifications": [
        "Reviewers mention quiet seating and wifi"
      ],
      "latitude": 41.878,
      "longitude": -87.629,
      "name": "Intelligentsia Coffee",
      "price": 2,
      "rating": 8.7,
      "tel": "(312) 253-0594",
      "website": "https://www.intelligentsiacoffee.com"
    }
  ],
  "summary": "Three well-rated cafes with quiet seating downtown."
}
```

### Get place details

Look up the full profile of a place, including hours and contact details.

**Inputs**

- Place ID (`fsq_place_id`, text, required): The Foursquare place ID to look up.

**Outputs**: Detailed information about a single place.

- `address` (text): Full formatted street address.
- `categories` (list): Category labels, such as 'Coffee Shop' or 'Italian Restaurant'.
- `description` (text): Description of the place.
- `email` (text): Contact email address for the place.
- `fsq_place_id` (text): Foursquare place ID. Pass this to the other Foursquare actions.
- `hours` (text): Opening hours, written out for reading.
- `latitude` (number): Latitude of the place.
- `longitude` (number): Longitude of the place.
- `name` (text): Name of the place.
- `open_now` (true/false): Whether the place is open right now.
- `price` (number): Price tier from 1 (most affordable) to 4 (most expensive).
- `rating` (number): Foursquare rating from 0 to 10.
- `tel` (text): Phone number of the place.
- `website` (text): Website of the place.

**Example output**

```json
{
  "address": "53 W Jackson Blvd, Chicago, IL 60604",
  "categories": [
    "Coffee Shop"
  ],
  "description": "Third-wave coffee bar in the Loop.",
  "email": "hello@intelligentsiacoffee.com",
  "fsq_place_id": "4b6f0b40f964a520bce02ce3",
  "hours": "Mon-Fri 6:00 AM-7:00 PM; Sat-Sun 7:00 AM-7:00 PM",
  "latitude": 41.878,
  "longitude": -87.629,
  "name": "Intelligentsia Coffee",
  "open_now": true,
  "price": 2,
  "rating": 8.7,
  "tel": "(312) 253-0594",
  "website": "https://www.intelligentsiacoffee.com"
}
```

### Get place photos

List the photos Foursquare users have uploaded for a place.

**Inputs**

- Place ID (`fsq_place_id`, text, required): The Foursquare place ID to get photos for.
- Limit (`limit`, number): Maximum number of photos to return, up to 50. From 1 to 50.

**Outputs**

- `count` (number): Number of photos returned.
- `photos` (list): Photos uploaded for the place.

**Example output**

```json
{
  "count": 1,
  "photos": [
    {
      "classifications": [
        "indoor"
      ],
      "created_at": "2024-03-02T18:41:11.000Z",
      "fsq_photo_id": "5b2c3d4e5f6a7b8c9d0e1f2a",
      "height": 1920,
      "url": "https://fastly.4sqi.net/img/general/original/1234_abcdef.jpg",
      "width": 1440
    }
  ]
}
```

### Get place tips

List the short tips Foursquare users have left about a place.

**Inputs**

- Place ID (`fsq_place_id`, text, required): The Foursquare place ID to get tips for.
- Limit (`limit`, number): Maximum number of tips to return, up to 50. From 1 to 50.

**Outputs**

- `count` (number): Number of tips returned.
- `tips` (list): Tips left about the place.

**Example output**

```json
{
  "count": 1,
  "tips": [
    {
      "agree_count": 12,
      "created_at": "2024-04-18T15:22:04.000Z",
      "disagree_count": 0,
      "fsq_tip_id": "5a1b2c3d4e5f6a7b8c9d0e1f",
      "lang": "en",
      "text": "Grab a seat upstairs -- quieter and there are outlets.",
      "url": "https://foursquare.com/item/5a1b2c3d4e5f6a7b8c9d0e1f"
    }
  ]
}
```

### Search places

Search the Foursquare Places database by keyword and location, for example coffee shops in Chicago.

**Inputs**

- Query (`query`, text): What to search for -- a place name, category name, or keyword such as 'tacos'. Required unless you filter by category IDs instead.
- Near (`near`, text): A place to search in, such as 'Chicago, IL'. Provide this or a latitude/longitude.
- Latitude, longitude (`ll`, text): Coordinates to search around, as 'latitude,longitude' (e.g. 41.8781,-87.6298). Provide this or a place name.
- Radius (meters) (`radius`, number): How far from the coordinates to search, in meters. Only applies alongside a latitude/longitude. Defaults to 22000. From 0 to 100000.
- Category IDs (`fsq_category_ids`, text): Only return places in these Foursquare category IDs, separated by commas.
- Minimum price tier (`min_price`, number): Cheapest price tier to include, from 1 to 4. From 1 to 4.
- Maximum price tier (`max_price`, number): Most expensive price tier to include, from 1 to 4. From 1 to 4.
- Open now (`open_now`, true/false): Set to true to only include places that are open right now. Places with no published hours are left out.
- Sort results by (`sort`, text): How to order the places. Defaults to relevance. One of: `RELEVANCE` (Best match), `RATING` (Highest rated), `DISTANCE` (Closest first), `POPULARITY` (Most popular). Default: `RELEVANCE`.
- Limit (`limit`, number): Maximum number of places to return, up to 50. Defaults to 10. From 1 to 50.

**Outputs**

- `count` (number): Number of places returned.
- `places` (list): Matching places, best match first.

**Example output**

```json
{
  "count": 1,
  "places": [
    {
      "address": "53 W Jackson Blvd, Chicago, IL 60604",
      "categories": [
        "Coffee Shop"
      ],
      "distance": 120,
      "fsq_place_id": "4b6f0b40f964a520bce02ce3",
      "latitude": 41.878,
      "longitude": -87.629,
      "name": "Intelligentsia Coffee",
      "price": 2,
      "rating": 8.7,
      "tel": "(312) 253-0594",
      "website": "https://www.intelligentsiacoffee.com"
    }
  ]
}
```