Description

Allows Foursquare users to add a new venue. All fields are optional, except for ll and name.

Before adding a place, please make sure your data is properly formatted to adhere to our style guide here.

Category ID’s

Although optional, we strongly recommend that developers pass in the primaryCategoryId parameter to assign the new venue a category. The resulting venues become more meaningful within Foursquare and are more easily searchable by other users. We recommend that applications show their users our category hierarchy (obtained from venues/categories) and allow them to choose something suitable.

Duplicate Venue Errors

The method may return an HTTP 409 error if the new venue looks like a duplicate of an existing venue. This error response will include two useful values: candidateDuplicateVenues and ignoreDuplicatesKey.

In this situation, you can either:

  • Use one of the candidateDuplicateVenues included in the response of the 409 error. This will not create a new venue.
  • Ignore duplicates and force the addition of a new venue by resubmitting the same venue add request with two additional parameters: ignoreDuplicates set to true and ignoreDuplicatesKey set to the value from the earlier error response.

What you do with the duplicates should be up to your users; developers should not always just pass ignoreDuplicates=true or always trust the top duplicate candidate.


Request

POST https://api.foursquare.com/v2/venues/add


Authentication

User authentication.


Parameters

Name Example Description
name Habana Outpost required The name of the venue.
ll 44.3,37.2 required Latitude and longitude of the venue, as accurate as is known.
address 42 Wallaby Way The address of the venue.
crossStreet at Fulton St The nearest intersecting street or streets.
city New York The city name where this venue is.
state New York The nearest state or province to the venue.
zip AE1234 The zip or postal code for the venue.
phone 00 01 23 1234 The phone number of the venue.
twitter eathabana The twitter handle of the venue.
primaryCategoryId 4bf58dd8d48988d1d4941735 The ID of the category to which you want to assign this venue.
description We are a family owned and operated business with our customers’ satisfaction … A freeform description of the venue, up to 160 characters.
url http://www.mercurylounge.com The url of the homepage of the venue.
ignoreDuplicates true A boolean flag telling the server to ignore duplicates and force the addition of this venue.
ignoreDuplicatesKey bb29f2481666444c Required if ignoreDuplicates is true. This key will be available in the response of the HTTP 409 error of the first (failed) attempt to add venue.

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.
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.
storeId The manager’s internal identifier for the venue.
description Description of the venue provided by venue owner.
createdAt Seconds since epoch when the venue was created.
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
attributes Attributes associated with the venue, such as price tier, whether the venue takes reservations, and parking availability.
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.