Get List Details
Public Beta Feature
This documentation covers a feature currently in Public Beta. Access is available to anyone interested in building personalized experiences for their end-users.
This feature is subject to the Personalization API (Self-Service) Public Beta End user License Agreement.
API Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| list_id | string | Yes | The ID of the list to be acted upon. |
| v | string | Yes | The API version date as documented here; e.g. 20231010 |
Example Success Response
{
"meta": {
"code": 200,
"requestId": "654a92f35669622b047c40d4"
},
"notifications": [
{
"type": "notificationTray",
"item": {
"unreadCount": 0
}
}
],
"response": {
"list": {
"id": "5ad0e20146e1b61376729df3",
"name": "A Foursquare history tour in NYC",
"description": "The places on this list hold a special place in the history of Foursquare. As we celebrate our 10th anniversary on 4SQDay - 2019, we share these ten places and their significance in our journey.",
"type": "others",
"user": {
"id": "23438729",
"firstName": "Foursquare City Guide",
"handle": "FoursquareGuide",
"privateProfile": false,
"gender": "none",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/p/foursquare-city-guide/23438729",
"canonicalPath": "/FoursquareGuide",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/23438729-TODURDIUDUMY4JF5.png"
},
"type": "page",
"isAnonymous": false
},
"editable": false,
"public": true,
"collaborative": false,
"url": "/FoursquareGuide/list/a-foursquare-history-tour-in-nyc",
"canonicalUrl": "https://foursquare.com/FoursquareGuide/list/a-foursquare-history-tour-in-nyc",
"canonicalPath": "/FoursquareGuide/list/a-foursquare-history-tour-in-nyc",
"createdAt": 1523638785,
"updatedAt": 1555356575,
"photo": {
"id": "4fad38e6e4b0348adb9a1f81",
"createdAt": 1336752358,
"prefix": "https://fastly.4sqi.net/img/general/",
"suffix": "/lzF1d7-k6UyfdeTG7OHoI3htft0ped1oObzkAuPZH1w.jpg",
"width": 720,
"height": 540,
"demoted": false,
"adminNotes": [],
"containsFace": false,
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
},
"visibility": "public"
},
"logView": true,
"guideType": "itinerary",
"guide": true,
"visitedCount": 0,
"venueCount": 10,
"categories": {
"count": 4,
"items": [
{
"category": {
"id": "4bf58dd8d48988d116941735",
"name": "Bar",
"pluralName": "Bars",
"shortName": "Bar",
"icon": {
"prefix": "https://ss3.4sqi.net/img/categories_v2/nightlife/pub_",
"mapPrefix": "https://ss3.4sqi.net/img/categories_map/nightlife/bar",
"suffix": ".png"
},
"categoryCode": 13003
},
"count": 5
},
{
"category": {
"id": "4bf58dd8d48988d124941735",
"name": "Office",
"pluralName": "Offices",
"shortName": "Office",
"icon": {
"prefix": "https://ss3.4sqi.net/img/categories_v2/building/default_",
"mapPrefix": "https://ss3.4sqi.net/img/categories_map/building/default",
"suffix": ".png"
},
"categoryCode": 11124
},
"count": 3
},
{
"category": {
"id": "4bf58dd8d48988d1d0941735",
"name": "Dessert Shop",
"pluralName": "Dessert Shops",
"shortName": "Desserts",
"icon": {
"prefix": "https://ss3.4sqi.net/img/categories_v2/food/dessert_",
"mapPrefix": "https://ss3.4sqi.net/img/categories_map/food/dessert",
"suffix": ".png"
},
"categoryCode": 13040
},
"count": 1
},
{
"category": {
"id": "63be6904847c3692a84b9bb6",
"name": "Cafe, Coffee, and Tea House",
"pluralName": "Cafes, Coffee, and Tea Houses",
"shortName": "Cafe, Coffee, and Tea House",
"icon": {
"prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
"mapPrefix": "https://ss3.4sqi.net/img/categories_map/food/coffeeshop",
"suffix": ".png"
},
"categoryCode": 13032
},
"count": 1
}
]
},
"following": false,
"followers": {
"count": 143,
"items": [
{
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false,
"tips": {"count": 15},
"lists": {"groups": [{"type": "created", "count": 71, "items": []}]},
"homeCity": "Praha, Česká republika",
"bio": "",
"contact": {},
"superuser": 9
},
{
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false,
"tips": {"count": 667},
"lists": {"groups": [{"type": "created", "count": 13, "items": []}]},
"homeCity": "Winter Haven, Florida",
"bio": "Love exploring new places and making friends. Married to Ryan Larrabee. Here to life blog and make friends.",
"contact": {"facebook": "1285570303"}
},
{
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false,
"tips": {"count": 1},
"lists": {"groups": [{"type": "created", "count": 5, "items": []}]},
"homeCity": "New York, NY",
"bio": "",
"contact": {"twitter": "dharathtot"},
"superuser": 3
},
{
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false,
"tips": {"count": 192},
"lists": {"groups": [{"type": "created", "count": 48, "items": []}]},
"homeCity": "",
"bio": "Product Manager @ Lyft",
"contact": {"twitter": "johnsmith", "facebook": "1234567890"},
"superuser": 8
},
{
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false,
"tips": {"count": 19},
"lists": {"groups": [{"type": "created", "count": 2, "items": []}]},
"homeCity": "Harrison Township, MI",
"bio": "",
"contact": {"facebook": "1411655446"}
}
]
},
"collaborators": {
"count": 0,
"items": []
},
"sort": "list-order",
"listItems": {
"count": 10,
"items": [
{
"id": "t4e5b9cdcb61c4aaa3e1891e5",
"createdAt": 1523639309,
"tip": {
"id": "4e5b9cdcb61c4aaa3e1891e5",
"createdAt": 1314626780,
"text": "This place was ground zero for the blogger/Gawker scene in 2003-2004 and has always been a big hangout for the early dodgeball.com crowd. My brain is hardwired to use \"The Magician\" as a test search.",
"type": "user",
"canonicalUrl": "https://foursquare.com/item/4e5b9cdcb61c4aaa3e1891e5",
"canonicalPath": "/item/4e5b9cdcb61c4aaa3e1891e5",
"likes": {
"count": 25,
"groups": [],
"summary": "25 likes"
},
"logView": true,
"agreeCount": 29,
"disagreeCount": 0,
"lastVoteText": "Upvoted Sep 18",
"lastUpvoteTimestamp": 1695074275,
"todo": {"count": 19},
"saves": {},
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
}
},
"photo": {
"id": "5833ae086d632545b11cfbb8",
"createdAt": 1479781896,
"prefix": "https://fastly.4sqi.net/img/general/",
"suffix": "/47321_C5McLAz3K7HEN7OaemMpdAyoSMp18W0Al0hYqGBw05U.jpg",
"width": 1440,
"height": 1440,
"demoted": false,
"adminNotes": [],
"containsFace": false,
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
},
"visibility": "public"
},
"venue": {
"id": "3fd66200f964a52005e41ee3",
"name": "The Magician"
},
"index": 0,
"isNew": true
},
{
"id": "t4e5bbdd1b61c4aaa3e1a73cb",
"createdAt": 1523639463,
"tip": {
"id": "4e5bbdd1b61c4aaa3e1a73cb",
"createdAt": 1314635217,
"text": "Bleecker Bar may be the home to the very first checkin ever (2001?) One of the orignal use cases from the dodgeball.com days: \"I want to know when my friends are at the bar watching a baseball game.\"",
"type": "user",
"canonicalUrl": "https://foursquare.com/item/4e5bbdd1b61c4aaa3e1a73cb",
"canonicalPath": "/item/4e5bbdd1b61c4aaa3e1a73cb",
"likes": {
"count": 28,
"groups": [],
"summary": "28 likes"
},
"logView": true,
"agreeCount": 37,
"disagreeCount": 0,
"todo": {"count": 11},
"saves": {},
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
}
},
"photo": {
"id": "50b881b2e4b0fb1ae2282efc",
"createdAt": 1354269106,
"prefix": "https://fastly.4sqi.net/img/general/",
"suffix": "/18841900_C9fYlkpnssWl1qJ7k52G9ssaLBR9vtPNnwDpgLSz4y8.jpg",
"width": 540,
"height": 540,
"demoted": false,
"adminNotes": [],
"containsFace": false,
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
},
"visibility": "public"
},
"venue": {
"id": "3fd66200f964a520dee51ee3",
"name": "Bleecker Street Bar"
},
"index": 1,
"isNew": true
},
{
"id": "t4e5b9ae9b61c4aaa3e1875c8",
"createdAt": 1523639322,
"tip": {
"id": "4e5b9ae9b61c4aaa3e1875c8",
"createdAt": 1314626281,
"text": "This was a go-to during my grad school days at NYU, Ace Bar was always used as the \"example\" for dodgeball.com & foursquare use cases. It's still the first place I think of when testing new features.",
"type": "user",
"canonicalUrl": "https://foursquare.com/item/4e5b9ae9b61c4aaa3e1875c8",
"canonicalPath": "/item/4e5b9ae9b61c4aaa3e1875c8",
"likes": {
"count": 37,
"groups": [],
"summary": "37 likes"
},
"logView": true,
"agreeCount": 47,
"disagreeCount": 0,
"todo": {"count": 24},
"saves": {},
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
}
},
"photo": {
"id": "5ad0c9156818073466924d26",
"createdAt": 1523632405,
"prefix": "https://fastly.4sqi.net/img/general/",
"suffix": "/32_B1C4dGLU8q2d3XYG39q8oMU19gIcVUBgqTlUVsNFTtU.png",
"width": 2146,
"height": 1260,
"demoted": false,
"adminNotes": [],
"containsFace": false,
"user": {
"id": "12345",
"firstName": "John",
"lastName": "Smith",
"handle": "johnsmith",
"privateProfile": false,
"gender": "male",
"countryCode": "US",
"followingRelationship": "none",
"canonicalUrl": "https://foursquare.com/user/12345",
"canonicalPath": "/johnsmith",
"photo": {
"prefix": "https://fastly.4sqi.net/img/user/",
"suffix": "/blank_boy.png"
},
"isAnonymous": false
},
"visibility": "public"
},
"venue": {
"id": "3fd66200f964a520f8e41ee3",
"name": "Ace Bar"
},
"index": 2,
"isNew": true
}
]
},
"completedCount": 0
}
}
}