Description

Returns a list of recommended venues near the current location. For more robust information about the venues themselves (photos/tips/etc.), please see our venue details endpoint.

If authenticated, the method will personalize the ranking based on you and your friends.


Request

GET https://api.foursquare.com/v2/venues/explore


Authentication

User or userless authentication.


Parameters

Name Example Description
ll 44.3,37.2 required unless near is provided. Latitude and longitude of the user’s location.
near Chicago, IL required unless ll is provided. A string naming a place in the world. If the near string is not geocodable, returns a failed_geocode error. Otherwise, searches within the bounds of the geocode and adds a geocode object to the response.
llAcc 10000.0 Accuracy of latitude and longitude, in meters.
alt 0 Altitude of the user’s location, in meters.
altAcc 10000.0 Accuracy of the user’s altitude, in meters.
radius 250 Radius to search within, in meters. If radius is not specified, a suggested radius will be used based on the density of venues in the area. The maximum supported radius is currently 100,000 meters.
section food One of food, drinks, coffee, shops, arts, outdoors, sights, trending, nextVenues (venues frequently visited after a given venue), or topPicks (a mix of recommendations generated without a query from the user). Choosing one of these limits results to venues with the specified category or property.
query tacos A term to be searched against a venue’s tips, category, etc. The query parameter has no effect when a section is specified.
limit 10 Number of results to return, up to 50.
offset 20 Used to page through results, up to 50.
novelty new Pass new or old to limit results to places the acting user hasn’t been or has been, respectively. Omitting this parameter returns a mixture of old and new venues.
friendVisits visited Pass visited or notvisited to limit results to places the acting user’s friends have or haven’t been, respectively. Omitting this parameter returns a mixture of venues to which the user’s friends have or haven’t been.
time any Pass any to retrieve results for any time of day. Omitting this parameter returns results targeted to the current time of day.
day any Pass any to retrieve results for any day of the week. Omitting this parameter returns results targeted to the current day of the week.
lastVenue 4ef0e7cf7beb5932d5bdeb4e A venue ID to use in combination with the intent=nextVenues parameter, which returns venues users often visit after a given venue. If intent=nextVenues is specified but lastVenue is not, the user’s last check-in will be used if it is within 2 hours. If the user has not checked in within the last 2 hours, no results will be returned.
openNow 1 Boolean flag to only include venues that are open now. This prefers official provider hours but falls back to popular check-in hours.
sortByDistance 1 Boolean flag to sort the results by distance instead of relevance.
price 2,3 Comma separated list of price points. Currently the valid range of price points are [1,2,3,4], 1 being the least expensive, 4 being the most expensive. For food venues, in the United States, 1 is < $10 an entree, 2 is $10-$20 an entree, 3 is $20-$30 an entree, 4 is > $30 an entree.
saved 1 Boolean flag to only include venues that the user has saved on their To-Do list or to another list.

Try it Now!


Response Fields

Field Description
warning Presents an object with a text field that contains a warning message, if applicable (i.e. not enough results, try doing X).
groups An array of objects representing groups of recommendations. Each group contains a type such as “recommended” a human-readable (eventually localized) name such as “Recommended Places,” and an array items of recommendation objects.
suggestedRadius (optional) If no radius was specified in the request, presents the radius that was used for the query (based upon the density of venues in the query area).
headerLocation A text name for the location the user searched, e.g. “SoHo”.
headerFullLocation A full text name for the location the user searched, e.g. “SoHo, New York”.
headerMessage A message to the user based on their current context, e.g. “Suggestions for Tuesday afternoon”.
id A unique string identifier for this venue.
name The best known name for this venue.
location An object containing none, some, or all of address (street address), crossStreet, city, state, postalCode, country, lat, lng, and distance. All fields are strings, except for lat, lng, and distance. Distance is measured in meters. Some venues have their locations intentionally hidden for privacy reasons (such as private residences). If this is the case, the parameter isFuzzed will be set to true, and the lat/lng parameters will have reduced precision.
categories An array, possibly empty, of categories that have been applied to this venue. One of the categories will have a primary field indicating that it is the primary category for the venue. For the complete category tree, see categories.

Response

{
  "meta": {
    "code": 200,
    "requestId": "5ac51ef86a607143de8eg5cb"
  },
  "response": {
    "warning": {
      "text": "There aren't a lot of results near you. Try something more general, reset your filters, or expand the search area."
    },
    "suggestedRadius": 600,
    "headerLocation": "Lower East Side",
    "headerFullLocation": "Lower East Side, New York",
    "headerLocationGranularity": "neighborhood",
    "totalResults": 230,
    "suggestedBounds": {
      "ne": {
        "lat": 40.724216906965616,
        "lng": -73.9896507407283
      },
      "sw": {
        "lat": 40.72151724718017,
        "lng": -73.98693222860872
      }
    },
    "groups": [
      {
        "type": "Recommended Places",
        "name": "recommended",
        "items": [
          {
            "reasons": {
              "count": 0,
              "items": [
                {
                  "summary": "This spot is popular",
                  "type": "general",
                  "reasonName": "globalInteractionReason"
                }
              ]
            },
            "venue": {
              "id": "49b6e8d2f964a52016531fe3",
              "name": "Russ & Daughters",
              "location": {
                "address": "179 E Houston St",
                "crossStreet": "btwn Allen & Orchard St",
                "lat": 40.72286707707289,
                "lng": -73.98829148466851,
                "labeledLatLngs": [
                  {
                    "label": "display",
                    "lat": 40.72286707707289,
                    "lng": -73.98829148466851
                  }
                ],
                "distance": 130,
                "postalCode": "10002",
                "cc": "US",
                "city": "New York",
                "state": "NY",
                "country": "United States",
                "formattedAddress": [
                  "179 E Houston St (btwn Allen & Orchard St)",
                  "New York, NY 10002",
                  "United States"
                ]
              },
              "categories": [
                {
                  "id": "4bf58dd8d48988d1f5941735",
                  "name": "Gourmet Shop",
                  "pluralName": "Gourmet Shops",
                  "shortName": "Gourmet",
                  "icon": {
                    "prefix": "https://ss3.4sqi.net/img/categories_v2/shops/food_gourmet_",
                    "suffix": ".png"
                  },
                  "primary": true
                }
              ],
              "venuePage": {
                "id": "77298563"
              }
            }
          }
        ]
      }
    ]
  }
}