Description

Returns a list of venues near the current location, optionally matching a search term.

To ensure the best possible results, pay attention to the intent parameter below. And if you’re looking for “top” venues or recommended venues, use the explore endpoint instead.

Note that most of the fields returned inside a venue can be optional. The user may create a venue that has no address, city or state (the venue is created instead at the lat/long specified). Your client should handle these conditions safely.


Request

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


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. Optional if using intent=global
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.
intent checkin One of the values below, indicating your intent in performing the search. If no value is specified, defaults to checkin.

Value Description
checkin Finds venues that the current user (or, for userless requests, a typical user) is likely to checkin to at the provided ll, at the current moment in time. This is the intent we recommend most apps use.
global Finds the most globally relevant venues for the search, independent of location. Ignores all parameters other than query and limit.
browse Find venues within a given area. Unlike the checkin intent, browse searches an entire region instead of only finding venues closest to a point. A region to search can be defined by including either the ll and radius parameters, or the sw and ne. The region will be circular if you include the ll and radius parameters, or a bounding box if you include the sw and ne parameters.
match Finds venues that are near-exact matches for the given parameters. This intent is primarily used when trying to harmonize an existing place database with Foursquare’s and is highly sensitive to the provided location. The results will be sorted by best match first, taking distance and spelling variations into account. name and ll are the only required parameters for this intent, but we also suggest sending phone, address, city, state, zip, and twitter for better results. There’s no specified format for these parameters—we do our best to normalize them and drop them from the search if unsuccessful.

radius 250 Limit results to venues within this many meters of the specified location. Defaults to a city-wide area. Only valid for requests with intent=browse, or requests with intent=checkin and categoryId or query. Does not apply to intent=match requests. The maximum supported radius is currently 100,000 meters.
sw 44.3,37.2 With ne, limits results to the bounding box defined by the latitude and longitude given by sw as its south-west corner, and ne as its north-east corner. The bounding box is only supported for intent=browse searches. Not valid with ll or radius. Bounding boxes with an area up to approximately 10,000 square kilometers are supported.
ne 44.1,37.4 See sw.
query tacos A search term to be applied against venue names.
limit 10 Number of results to return, up to 50.
categoryId 4bf58dd8d488d11094, 4bf58dd8d1bd941735 A comma separated list of categories to limit results to. If you specify categoryId. specifying a radius may improve results. If specifying a top-level category, all sub-categories will also match the query. Does not apply to intent=match requests.
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.
url http://nymag.com/food A third-party URL which we will attempt to match against our map of venues to URLs.
providerId nymag Identifier for a known third party that is part of our map of venues to URLs, used in conjunction with linkedId.
linkedId 1002207971611 Identifier used by third party specified in providerId, which we will attempt to match against our map of venues to URLs.

Try it Now!


Response Fields

Field Description
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.
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.
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.
hereNow Information about who is here now. If present, there is always a count, the number of people here. If viewing details and there is a logged-in user, there is also a groups field with friends and others as types.
createdAt Seconds since epoch when the venue was created.
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.
beenHere Contains count of the number of times the acting user has been here. Absent if there is no acting user.
shortUrl A short URL for this venue, e.g. http://4sq.com/Ab123D
canonicalUrl The canonical URL for this venue, e.g. https://foursquare.com/v/foursquare-hq/4ab7e57cf964a5205f7b20e3
like Indicates if the current user has liked this venue.
dislike Indicates if the current user has disliked this venue.
roles Present if and only if the current user has at least one assigned role for this venue. The value is a list of all of the current user’s assigned roles for this venue. Possible values for each element of the list are manager and employee. Subject to change as additional roles may be defined.

Response

{
  "meta": {
    "code": 200,
    "requestId": "599e0347f594df1fa96abb99"
  },
  "response": {
    "geocode": {
      "what": "",
      "where": "new york ny",
      "center": {
        "lat": 40.742185,
        "lng": -73.992602
      },
      "displayString": "New York, NY, United States",
      "cc": "US"
    },
    "groups": [
      {
        "type": "Recommended Places",
        "name": "recommended",
        "items": [
          {
            "reasons": {
              "count": 0,
              "items": [
                {
                  "summary": "This spot is popular",
                  "type": "general",
                  "reasonName": "globalInteractionReason"
                }
              ]
            },
            "venue": {
              "id": "412d2800f964a520df0c1fe3",
              "name": "Central Park",
              "contact": {
                "phone": "2123106600",
                "formattedPhone": "(212) 310-6600",
                "twitter": "centralparknyc",
                "instagram": "centralparknyc",
                "facebook": "37965424481",
                "facebookUsername": "centralparknyc",
                "facebookName": "Central Park"
              },
              "location": {
                "address": "59th St to 110th St",
                "crossStreet": "5th Ave to Central Park West",
                "lat": 40.78408342593807,
                "lng": -73.96485328674316,
                "labeledLatLngs": [
                  {
                    "label": "display",
                    "lat": 40.78408342593807,
                    "lng": -73.96485328674316
                  }
                ],
                "postalCode": "10028",
                "cc": "US",
                "city": "New York",
                "state": "NY",
                "country": "United States",
                "formattedAddress": [
                  "59th St to 110th St (5th Ave to Central Park West)",
                  "New York, NY 10028",
                  "United States"
                ]
              },
              "categories": [
                {
                  "id": "4bf58dd8d48988d163941735",
                  "name": "Park",
                  "pluralName": "Parks",
                  "shortName": "Park",
                  "icon": {
                    "prefix": "https://ss3.4sqi.net/img/categories_v2/parks_outdoors/park_",
                    "suffix": ".png"
                  },
                  "primary": true
                }
              ],
              "verified": true,
              "stats": {
                "checkinsCount": 363538,
                "usersCount": 171751,
                "tipCount": 1588
              },
              "url": "http://www.centralparknyc.org",
              "beenHere": {
                "count": 0,
                "marked": false,
                "lastCheckinExpiredAt": 0
              },
              "hours": {
                "status": "Open until 1:00 AM",
                "isOpen": true,
                "isLocalHoliday": false
              },
              "storeId": "",
              "hereNow": {
                "count": 23,
                "summary": "23 people are here",
                "groups": [
                  {
                    "type": "others",
                    "name": "Other people here",
                    "count": 23,
                    "items": []
                  }
                ]
              }
            }
          }
        ]
      }
    ]
  }
}