Venue Search
Description
Returns a list of venues near the current location, optionally matching a search term.
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. For more robust venue information (photos/tips/etc.), please see our venue details endpoint.
Request
GET https://api.foursquare.com/v2/venues/search
Authentication
This endpoint supports userless or user authentication.
Supported | Description |
---|---|
Userless | required unless OAuth token is provided. A valid Client ID and Secret in the query string of each request. Eg. &client_id=XXXX&client_secret=XXXX |
User | required unless Client ID and Secret are provided. A valid OAuth access token in the query string of each request. Eg. &oauth_token=XXXX |
For more information about these authentication methods and how to obtain an access token, see the Authentication docs.
Parameters
Name | Example | Description |
---|---|---|
ll | 40.74224,-73.99386 | 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. |
radius | 250 | 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. |
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. |
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. |
Response Fields
Field | Description |
---|---|
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": "5ac51d7e6a607143d811cecb"
},
"response": {
"venues": [
{
"id": "5642aef9498e51025cf4a7a5",
"name": "Mr. Purple",
"location": {
"address": "180 Orchard St",
"crossStreet": "btwn Houston & Stanton St",
"lat": 40.72173744277209,
"lng": -73.98800687282996,
"labeledLatLngs": [
{
"label": "display",
"lat": 40.72173744277209,
"lng": -73.98800687282996
}
],
"distance": 8,
"postalCode": "10002",
"cc": "US",
"city": "New York",
"state": "NY",
"country": "United States",
"formattedAddress": [
"180 Orchard St (btwn Houston & Stanton St)",
"New York, NY 10002",
"United States"
]
},
"categories": [
{
"id": "4bf58dd8d48988d1d5941735",
"name": "Hotel Bar",
"pluralName": "Hotel Bars",
"shortName": "Hotel Bar",
"icon": {
"prefix": "https://ss3.4sqi.net/img/categories_v2/travel/hotel_bar_",
"suffix": ".png"
},
"primary": true
}
],
"venuePage": {
"id": "150747252"
}
}
]
}
}
Was this page helpful?