Response fields define the returnable metadata of the FSQ Places API. This data will be returned when requesting a Places Search or Place Details call. This page lists all place data fields and their groupings.
Types of Returnable :
Places Core Data
| Field | Description |
|---|---|
| fsq_id | A unique identifier for a FSQ Place (formerly known as Venue ID). |
| name | The best known name for the FSQ Place. |
| geocodes | Set of geocodes (latitude, longitude) for the Place. The primary coordinates are identified by the main latitude and longitude.Where available, other coordinates may include: - roof- drop_off- front_door- road |
| location | An object containing none, some, or all of the following fields: - address- address_extended- locality- dma- region- postcode- country- admin_region- post_town- po_box- cross_street- formatted_address- census_block: populated only for Places within the United States, in all other countries it will be null.NOTE: For the Autocomplete and Address Data APIs, the location object data is populated by the verified address data provided by Loqate. View Loqate's Full Coverage List → |
| categories | An array, possibly empty, of categories that describe the FSQ Place. Included subfields: id (Category ID), name (Category Label), and icon (Category's Icon).View the list of FSQ Categories → |
| chains | An array, possibly empty, of chains that the FSQ Place belongs to. Included subfields: id (Chain ID) and name (Chain Name).View the list of FSQ Chains → |
| related_places | An object containing the information for Places related to the FSQ Place. Included subfields: parent and children. Not all FSQ Places will have parent or children relationships.Some Children Place responses may not show a fsq_id. This indicates that Foursquare does not have enough data inputs to mark the Child Place as an official Place.Example: parent = Los Angeles International Airportchildren = Terminal 1, Terminal 2, Terminal 3... |
| timezone | A string that denotes the region representing the FSQ Place's timezone. |
| distance | The calculated distance (in meters) from the provided location (i.e. ll + radius OR near OR ne + sw) in the API call. This field will only be returned by the Place Search endpoint. |
| link | The URL associated with the corresponding Places Detail API call for the returned Place. |
| closed_bucket | Probability that a POI is Open/Closed. - VeryLikelyOpen, VeryLikelyClosed: 95% Confidence that a POI is Open/Closed respectively - LikelyOpen, LikelyClosed: 80% Confidence that a POI identified as LikelyOpen/VeryLikelyOpen is Open . Similarly, 80% Confidence that a POI marked as LikelyClosed/VeryLikelyClosed is Closed |
Places Rich Data
| Field | Description |
|---|---|
| description | A general description of the FSQ Place. Typically provided by the owner/claimant of the FSQ Place and/or updated by City Guide Superusers. |
| tel | The best known telephone number, with local formatting. |
| fax | The best known fax number, with local formatting. |
| The primary contact email address for the FSQ Place. | |
| website | The official website for the FSQ Place. |
| social_media | An object containing a FSQ Place's social media identifiers. Included subfields: facebook_id, instagram, and twitter. Not all FSQ Places will have all subfields. |
| verified | A boolean that indicates whether or not the FSQ Place has been claimed. |
| hours | An array containing the regular hours of operation, is_local_holiday, open_now, and a formatted display string.regular hours contain subfields: day (1 = Monday, 2 = Tuesday, 7 = Sunday) and open/close (24-hour time). |
| hours_popular | An array containing the hours during the week when a FSQ Place is most often visited. This place must have a minimum number of check-ins to be considered for the calculation. Similar to hours, this field contains subfields: day (1 = Monday, 2 = Tuesday, 7 = Sunday) and open/close (24-hour time). |
| rating | A numerical rating (from 0.0 to 10.0) of the FSQ Place, based on user votes, likes/dislikes, tips sentiment, and visit data. Not all FSQ Places will have a rating. NOTE: v3 does not include the following mapped ratings to colors as could be found in v2: - 0.0 = LightMediumGrey (#C7CDCF) - 0.0 <> 4.0 = Red (#E6092C)- 4.0 <> 5.0 = DarkOrange (#FF6701)- 5.0 <> 6.0 = Orange (#FF9600)- 6.0 <> 7.0 = Yellow (#FFC800)- 7.0 <> 8.0 = LightGreen (#C5DE35)- 8.0 <> 9.0 = Green (#73CF42)- 9.0 + = DarkGreen (#00B551) |
| stats | An object containing counts of photos, ratings, and tips. Included subfields: total_photos, total_ratings, and total_tips. |
| popularity | A measure of the FSQ Place's popularity, by foot traffic. This score is on a 0 to 1 scale and uses a 6-month span of Place visits for a given geographic area. |
| price | A numerical value (from 1 to 4) that best describes the pricing tier of the FSQ Place, based on known prices for menu items and other offerings. Values include: - 1 = Cheap- 2 = Moderate- 3 = Expensive- 4 = Very Expensive. |
| menu | A linked menu for the FSQ Place. |
| date_closed | The recorded date when the FSQ Place was marked as permanently closed in Foursquare's databases. This does not necessarily indicate the Place was actually closed on this date. |
| photos | An array of objects containing the following subfields: - id- created_at- classifications- prefix- suffix- width- height.For more information, see our Photos Guide → |
| tips | An array containing the following subfields: created_at and text. |
| tastes | An array of up to 25 tastes that best describe the FSQ Place. |
| features | A list of boolean tags that help to describe services and additional metadata offered by the Place (e.g. takes_reservations: true)For a full list of tags, see Places Tags. |
| store_id | The unique ID assigned to a venue in order to differentiate it from other stores within the same chain. |
| venue_reality_bucket | This attribute represents how “real” Foursquare believes a venue to be. As venues can be submitted directly by users, Foursquare uses a proprietary algorithm to assess real venues (public places like a popular restaurant, store, concert venue, etc) vs a private or nonexistent venue. Foursquare’s Venue Reality algorithm uses a combination of explicit and implicit signals (examples include number of searches on Foursquare, number of photos/tips submitted, number of check-ins, etc) to bucket venues with an output of Low, Medium, High, VeryHigh |
Address Data
| Field | Description |
|---|---|
| location | An object containing none, some, or all of the following fields: address, address_extended, locality, dma, region, postcode, country, admin_region, post_town, po_box, and cross_street. |
| geocodes | Set of geocodes (latitude, longitude) for the Place. The primary coordinates are identified by the main latitude and longitude.Where available, other coordinates may include: roof, drop_off, front_door, and road. |
Sample Places Data Response
{
"results": [
{
"fsq_id": "string",
"categories": [
{
"id": 0,
"name": "string",
"icon": {
"id": "string",
"created_at": "2023-10-11T16:32:04.439Z",
"prefix": "string",
"suffix": "string",
"width": 0,
"height": 0,
"classifications": [
"string"
],
"tip": {
"id": "string",
"created_at": "2023-10-11T16:32:04.439Z",
"text": "string",
"url": "string",
"lang": "string",
"agree_count": 0,
"disagree_count": 0
}
}
}
],
"chains": [
{
"id": "string",
"name": "string"
}
],
"closed_bucket": "string",
"date_closed": "2023-10-11",
"description": "string",
"distance": 0,
"email": "string",
"fax": "string",
"features": {
"payment": {
"credit_cards": {
"accepts_credit_cards": {},
"amex": {},
"discover": {},
"visa": {},
"diners_club": {},
"master_card": {},
"union_pay": {}
},
"digital_wallet": {
"accepts_nfc": {}
}
},
"food_and_drink": {
"alcohol": {
"bar_service": {},
"beer": {},
"byo": {},
"cocktails": {},
"full_bar": {},
"wine": {}
},
"meals": {
"bar_snacks": {},
"breakfast": {},
"brunch": {},
"lunch": {},
"happy_hour": {},
"dessert": {},
"dinner": {},
"tasting_menu": {}
}
},
"services": {
"delivery": {},
"takeout": {},
"drive_through": {},
"dine_in": {
"reservations": {},
"online_reservations": {},
"groups_only_reservations": {},
"essential_reservations": {}
}
},
"amenities": {
"restroom": {},
"smoking": {},
"jukebox": {},
"music": {},
"live_music": {},
"private_room": {},
"outdoor_seating": {},
"tvs": {},
"atm": {},
"coat_check": {},
"wheelchair_accessible": {},
"parking": {
"parking": {},
"street_parking": {},
"valet_parking": {},
"public_lot": {},
"private_lot": {}
},
"sit_down_dining": {},
"wifi": "string"
},
"attributes": {
"business_meeting": "string",
"clean": "string",
"crowded": "string",
"dates_popular": "string",
"dressy": "string",
"families_popular": "string",
"gluten_free_diet": "string",
"good_for_dogs": "string",
"groups_popular": "string",
"healthy_diet": "string",
"late_night": "string",
"noisy": "string",
"quick_bite": "string",
"romantic": "string",
"service_quality": "string",
"singles_popular": "string",
"special_occasion": "string",
"trendy": "string",
"value_for_money": "string",
"vegan_diet": "string",
"vegetarian_diet": "string"
}
},
"geocodes": {
"drop_off": {
"latitude": 0,
"longitude": 0
},
"front_door": {
"latitude": 0,
"longitude": 0
},
"main": {
"latitude": 0,
"longitude": 0
},
"road": {
"latitude": 0,
"longitude": 0
},
"roof": {
"latitude": 0,
"longitude": 0
}
},
"hours": {
"display": "string",
"is_local_holiday": true,
"open_now": true,
"regular": [
{
"close": "string",
"day": 0,
"open": "string"
}
]
},
"hours_popular": [
{
"close": "string",
"day": 0,
"open": "string"
}
],
"link": "string",
"location": {
"address": "string",
"address_extended": "string",
"admin_region": "string",
"census_block": "string",
"country": "string",
"cross_street": "string",
"dma": "string",
"formatted_address": "string",
"locality": "string",
"neighborhood": [
"string"
],
"po_box": "string",
"post_town": "string",
"postcode": "string",
"region": "string"
},
"menu": "string",
"name": "string",
"photos": [
{
"id": "string",
"created_at": "2023-10-11T16:32:04.439Z",
"prefix": "string",
"suffix": "string",
"width": 0,
"height": 0,
"classifications": [
"string"
],
"tip": {
"id": "string",
"created_at": "2023-10-11T16:32:04.439Z",
"text": "string",
"url": "string",
"lang": "string",
"agree_count": 0,
"disagree_count": 0
}
}
],
"popularity": 0,
"price": 0,
"rating": 0,
"related_places": {},
"social_media": {
"facebook_id": "string",
"instagram": "string",
"twitter": "string"
},
"stats": {
"total_photos": 0,
"total_ratings": 0,
"total_tips": 0
},
"store_id": "string",
"tastes": [
"string"
],
"tel": "string",
"timezone": "string",
"tips": [
{
"id": "string",
"created_at": "2023-10-11T16:32:04.439Z",
"text": "string",
"url": "string",
"lang": "string",
"agree_count": 0,
"disagree_count": 0
}
],
"venue_reality_bucket": "string",
"verified": true,
"website": "string"
}
],
"context": {
"geo_bounds": {
"circle": {
"center": {
"latitude": 0,
"longitude": 0
},
"radius": 0
}
}
}
}
For assistance and related questions, reach out to our team for support.