Description

Allows Foursquare users to add a new venue.

All fields are optional, except for ll and name.

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.

Adding Venues Without Authenticating Users First

This endpoint generally requires you to authenticate Foursquare users before you can add venues on their behalf. In some cases, we’ll make exceptions and allow applications to create new venues without authenticating any users.


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.
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.
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.
price An object containing the price tier from 1 (least pricey) - 4 (most pricey) and a message describing the price tier.
rating Numerical rating of the venue (0 through 10). Returned as part of an explore result, excluded in search results. Not all venues will have a rating.
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.
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.
tips Contains the total count of tips and groups with friends and others as groupTypes. Groups may change over time.
listed A grouped response of lists that contain this venue. Contains a summary string representing the acting user’s relationship to these lists. If an acting user is present, groups may include todos, created, edited, followed, friends, and others. If this venue is on the acting user’s todo list, those items will be included in the todos group.
tags An array of string tags applied to this venue.
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
likes The count of users who have liked this venue, and groups containing any friends and others who have liked it. The groups included are subject to change.
phrases List of phrases commonly seen in this venue’s tips, as well as a sample tip snippet and the number of tips this phrase appears in.
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.
flags Present only for venues returned in Explore search results. Current flags include: outsideRadius: A boolean indicating that the venue is outside the radius specified by the original query. Explore may return venues outside the requested radius in the case of a high-quality “exact match” to the query (e.g. if the user searches for [ace bar] in Brooklyn, we will still find the popular Ace Bar venue in Manhattan and return it with outsideRadius: true). exactMatch: A boolean indicating that the venue name was a strong match for the specified query (either it was an exact string match, or there was a large overlap between the query and the given venue’s name).