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

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

Category ID’s

We require the primaryCategoryId parameter for new venues in order to assign the 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.




User authentication.


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.
primaryCategoryId 4bf58dd8d48988d1d4941735 required The ID of the category to which you want to assign this venue.
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.
allCategoryIds 4bf58dd8d48988d1d4941735 Additional category IDs for the venue (up to two more, separated by a comma).
parentId 4b1d40b5f964a520ae0d24e3 If the venue is a subvenue of a larger venue (such as a coffee shop within a Target), set this attribute to the ID of the parent venue.
cc US The country code of the venue. This is optional but we recommend sending this parameter if your venue borders another country and you are getting formatting errors for the zip and/or phone.
twitter eathabana The twitter handle of the venue.
description We are a family owned and operated business with our customers’ satisfaction … A freeform description of the venue, up to 160 characters.
chainIds 556f676fbd6a75a99038d8ec A comma-delimited string of chain ID(s) for the venue (each venue can have up to five chain IDs, if applicable).
url 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.
canonicalUrl The canonical URL for this venue, e.g.
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.

Was this page helpful?
Thank you!