Description

Returns a list of recommended venues near the current location.

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.
venuePhotos 1 Boolean flag to include a photo in the response for each venue, if one is available. Default is 0 (no photos). Photos are returned as part of the venue JSON object.
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, which have an ordered list of objects which contain reasons and venue. The reasons are count and items, where each item has a type such as “social” and a message about why this place may be of interest to the acting user. The venues are compact venues that include stats and hereNow data. We encourage clients to be robust against the introduction or removal of group types by treating the groups as opaque objects to be displayed or by placing unfamiliar groups in a catchall group.
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.
contact An object containing none, some, or all of twitter, phone, and formattedPhone. All are strings.
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.
photos A count and groups of photos for this venue. Group types are checkin and venue. Not all items will be present.
tips Contains the total count of tips and groups with friends and others as groupTypes. Groups may change over time.
verified Boolean indicating whether the owner of this business has claimed it and verified the information.
stats Contains checkinsCount (total checkins ever here), usersCount (total users who have ever checked in here), and tipCount (number of tips here).
url URL of the venue’s website, typically provided by the venue manager.
hours Contains the hours during the week that the venue is open along with any named hours segments in a human-readable format. For machine readable hours see venues/hours
menu An object containing url and mobileUrl that display the menu information for this venue.
price An object containing the price tier from 1 (least pricey) - 4 (most pricey) and a message describing the price tier.
rating Numerical rating of the venue (0 through 10). Not all venues will have a rating.

Response

{
  "meta": {
    "code": 200,
    "requestId": "599ee939dd57971422a6b080"
  },
  "response": {
    "suggestedRadius": 600,
    "headerLocation": "SoHo",
    "headerFullLocation": "SoHo, New York",
    "headerLocationGranularity": "neighborhood",
    "query": "food",
    "totalResults": 8,
    "suggestedBounds": {
      "ne": {
        "lat": 40.72657082946255,
        "lng": -74.00392843616328
      },
      "sw": {
        "lat": 40.7238711696771,
        "lng": -74.00121067387556
      }
    },
    "groups": [
      {
        "type": "Recommended Places",
        "name": "recommended",
        "items": [
          {
            "reasons": {
              "count": 0,
              "items": [
                {
                  "summary": "This spot is popular",
                  "type": "general",
                  "reasonName": "globalInteractionReason"
                }
              ]
            },
            "venue": {
              "id": "56d92e05498e6c54b6325b19",
              "name": "San Carlo Osteria Piemonte",
              "contact": {
                "phone": "2126251212",
                "formattedPhone": "(212) 625-1212"
              },
              "location": {
                "address": "90 Thompson St",
                "crossStreet": "Spring St",
                "lat": 40.72522099956982,
                "lng": -74.00256955501942,
                "distance": 121,
                "postalCode": "10012",
                "cc": "US",
                "city": "New York",
                "state": "NY",
                "country": "United States",
                "formattedAddress": [
                  "90 Thompson St (Spring St)",
                  "New York, NY 10012",
                  "United States"
                ]
              },
              "categories": [
                {
                  "id": "4bf58dd8d48988d110941735",
                  "name": "Italian Restaurant",
                  "pluralName": "Italian Restaurants",
                  "shortName": "Italian",
                  "icon": {
                    "prefix": "https://ss3.4sqi.net/img/categories_v2/food/italian_",
                    "suffix": ".png"
                  },
                  "primary": true
                }
              ],
              "verified": false,
              "stats": {
                "checkinsCount": 339,
                "usersCount": 257,
                "tipCount": 19
              },
              "url": "http://www.sancarlonyc.com",
              "price": {
                "tier": 4,
                "message": "Very Expensive",
                "currency": "$"
              },
              "hasMenu": true,
              "rating": 9.3,
              "ratingColor": "00B551",
              "ratingSignals": 63,
              "menu": {
                "type": "Menu",
                "label": "Menu",
                "anchor": "View Menu",
                "url": "https://foursquare.com/v/san-carlo-osteria-piemonte/56d92e05498e6c54b6325b19/menu",
                "mobileUrl": "https://foursquare.com/v/56d92e05498e6c54b6325b19/device_menu"
              },
              "allowMenuUrlEdit": true,
              "beenHere": {
                "count": 0,
                "marked": false,
                "lastCheckinExpiredAt": 0
              },
              "hours": {
                "status": "Closed until 11:30 AM",
                "isOpen": false,
                "isLocalHoliday": false
              },
              "photos": {
                "count": 1,
                "groups": [
                  {
                    "type": "venue",
                    "name": "Venue photos",
                    "count": 1,
                    "items": [
                      {
                        "id": "586b352f0393cc3f5a8fd8ae",
                        "createdAt": 1483420975,
                        "prefix": "https://igx.4sqi.net/img/general/",
                        "suffix": "/20865647_UwXpRRAguYFxpEtTANzpDFymya30uJaLqoWLPhrVYf0.jpg",
                        "width": 1920,
                        "height": 1440,
                        "user": {
                          "id": "123456",
                          "firstName": "John",
                          "lastName": "Doe",
                          "gender": "male",
                          "photo": {
                            "prefix": "https://igx.4sqi.net/img/user/",
                            "suffix": "/KE2TWWNOUDJUEQGD.jpg"
                          }
                        },
                        "visibility": "public"
                      }
                    ]
                  }
                ]
              },
              "hereNow": {
                "count": 0,
                "summary": "Nobody here",
                "groups": []
              }
            },
            "tips": [
              {
                "id": "123456",
                "createdAt": 1502157995,
                "text": "Best Italian food in Soho. Nice ambiance. Good music (and live music on Sunday + Mondays). Bartenders, great cocktails. Friendly staff. Beautiful crowd.",
                "type": "user",
                "logView": true,
                "agreeCount": 0,
                "disagreeCount": 0,
                "todo": {
                  "count": 0
                },
                "user": {
                  "id": "123456",
                  "firstName": "John",
                  "lastName": "Doe",
                  "gender": "male"
                }
              }
            ],
            "referralId": "e-3-56d92e05498e6c54b6325b19-0"
          }
        ]
      }
    ]
  }
}