Search Venue Recommendations

Public Beta Feature

This documentation covers a feature currently in Public Beta. Access is available to anyone interested in building personalized experiences for their end-users.

This feature is subject to the Personalization API (Self-Service) Public Beta End user License Agreement.

API Parameters

• version
  string
  The API version date as documented here; e.g. 20231010

• query
  string
  A string to be searched against a venue's tips, category, etc. The query parameter has no effect when a section is specified.

• ll
  string
  The latitude/longitude around which to retrieve place information. This must be specified as latitude,longitude (e.g., ll=41.8781,-87.6298). Required if near is not specified.

• radius
  int32
  Limit results to venues within this many meters of the specified location. Defaults to a city-wide area. Only valid for requests that use categoryId or query. The maximum supported radius is currently 100,000 meters.

• sw/ne
  string
  The latitude/longitude representing the south/west and north/east points of a rectangle. Must be used to specify a rectangular search box.

• near
  string
  A string naming a place in the world. If the near string is not geocodable, returns a failed_geocode error. Required if ll is not specified.

• section
  string
  One of food, drinks, coffee, shops, arts, outdoors, sights, trending, nextVenues, or topPicks.

• categoryId
  string
  A comma separated list of categories to limit results to.

• novelty
  string
  Pass new or old to limit results to places the acting user hasn't been or has been, respectively.

• friendVisits
  string
  Pass visited or notvisited to limit results to places the acting user's friends have or haven't been.

• time/day
  string
  Pass any to retrieve results for any time of day or any day of the week.

• lastVenue
  string
  A venue ID to use with the intent=nextVenues parameter.

• openNow
  boolean
  Boolean flag to include only venues open now.

• price
  int32
  Comma separated list of price points ranging from 1 to 4.

• saved
  boolean
  Boolean flag to include venues that the user has saved.

• limit/offset
  int32
  Number of results to return, up to 50. Used to page through results.

Example API Call

curl --request GET \
     --url https://api.foursquare.com/v2/search/recommendations \
     --header 'accept: application/json'

Sample Response

{
  "meta": {
    "code": 200,
    "requestId": "6511d75a83245875ff2c1d75"
  },
  "response": {
    "group": {
      "results": [
        {
          "venue": {
            "id": "598eb122446ea6776a6083d4",
            "name": "Bumbershoot",
            "location": {
              "lat": 47.6062095,
              "lng": -122.3320708,
              "address": "Seattle, WA"
            },
            "categories": [{"name": "Music Venue"}],
            "stats": {"checkinsCount": 160}
          }
        }
      ],
      "totalResults": 7
    }
  }
}

Conclusion

This document provides a comprehensive overview of the API parameters and responses for venue recommendations.