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.

Try it Now!

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?