Description

Gives details about a list.


Request

GET https://api.foursquare.com/v2/lists/LIST_ID


Authentication

User or userless authentication.


Parameters

Name Example Description
LIST_ID 111XXXYY222 required ID for a user-created (e.g. /v2/lists/12381902N) or followed list or one of either USER_ID/tips (e.g. /v2/lists/32/tips)
limit 100 Number of results to return, up to 200.
offset 50 The number of results to skip. Used to page through results.
llBounds 30.13,-98.16,30.40,-97.28 Restricts the returned results to the input bounding box.
categoryId 4bf58dd8d48988d10e941 Restricts the returned results to venues matching the input category id.
sort recent Sorts the list items. Possible values are recent and nearby. Recent sorts the list items by the date added to the list and nearby sorts the list items by the distance from the center of the provided llBounds.

Response Fields

Field Description
id A unique identifier for this list.
name The user-entered name for this list.
description The user-entered list description.
user The user who created this list.
following Boolean indicating whether or not the acting user is following this list.
followers count of users who follow this list.
editable Boolean indicating whether the acting user can edit this list.
collaborative Boolean indicating whether this list is editable by the owner’s friends.
collaborators count of users who have edited this list. All items may not be present.
canonicalUrl The canonical URL for this list, e.g. https://foursquare.com/dens/list/a-brief-history-of-foursquare
photo A photo for this list.
venueCount The number of unique venues on the list.
visitedCount The number of venues on the list visited by the acting user. Absent if there is no acting user.
listItems count and items on this list. Items will be an array of venue objects.

Response

{
  "meta": {
    "code": 200,
    "requestId": "59ceb63b4434b905c507efbd"
  },
  "response": {
    "list": {
      "id": "5580721e498e7c48540bf83f",
      "name": "NYC's Best Rooftops",
      "description": "",
      "type": "others",
      "user": {
        "id": "23438729",
        "firstName": "Foursquare City Guide",
        "gender": "none",
        "photo": {
          "prefix": "https://igx.4sqi.net/img/user/",
          "suffix": "/23438729-TODURDIUDUMY4JF5.png"
        },
        "type": "page"
      },
      "editable": false,
      "public": true,
      "collaborative": false,
      "canonicalUrl": "https://foursquare.com/foursquare/list/nycs-best-rooftops",
      "createdAt": 1434481182,
      "updatedAt": 1497977804,
      "photo": {
        "id": "5420b376498e3fdb42d08c8d",
        "createdAt": 1411429238,
        "prefix": "https://igx.4sqi.net/img/general/",
        "suffix": "/18091_SPs8d1c-WsbNGV89cUg9ou1QOGa7YcDlRJLUlh1b6CQ.jpg",
        "width": 960,
        "height": 720,
        "visibility": "public"
      },
      "logView": true,
      "visitedCount": 0,
      "venueCount": 10,
      "categories": {
        "count": 9,
        "items": [
          {
            "category": {
              "id": "4bf58dd8d48988d116941735",
              "name": "Bar",
              "pluralName": "Bars",
              "shortName": "Bar",
              "icon": {
                "prefix": "https://ss3.4sqi.net/img/categories_v2/nightlife/pub_",
                "suffix": ".png"
              }
            },
            "count": 8
          },
          {
            "category": {
              "id": "4bf58dd8d48988d1fa931735",
              "name": "Hotel",
              "pluralName": "Hotels",
              "shortName": "Hotel",
              "icon": {
                "prefix": "https://ss3.4sqi.net/img/categories_v2/travel/hotel_",
                "suffix": ".png"
              }
            },
            "count": 4
          },
          //..
        ]
      },
      "following": false,
      "followers": {
        "count": 350
      },
      "collaborators": {
        "count": 0,
        "items": []
      },
      "sort": "list-order",
      "listItems": {
        "count": 10,
        "items": [
          {
            "id": "t57e71351498e9292956226a1",
            "createdAt": 1493226584,
            "tip": {
              "id": "57e71351498e9292956226a1",
              "createdAt": 1474761553,
              "text": "Awesome new rooftop with relatively cheap beer and great views of NYC. Get there right at 4pm when they open or be prepared to wait in line.",
              "type": "user",
              "canonicalUrl": "https://foursquare.com/item/57e71351498e9292956226a1",
              "logView": true,
              "agreeCount": 3,
              "disagreeCount": 0,
              "todo": {
                "count": 17
              },
              "saves": {},
              "user": {
              }
            },
            "venue": {
              "id": "57acf9af498e6b8d5376c2d4",
              "name": "Westlight",
              "contact": {
                "phone": "7183077100",
                "formattedPhone": "(718) 307-7100"
              },
              "location": {
                "address": "111 N 12th St",
                "crossStreet": "at Wythe Ave",
                "lat": 40.722294869596624,
                "lng": -73.95677447319031,
                "labeledLatLngs": [
                  {
                    "label": "display",
                    "lat": 40.722294869596624,
                    "lng": -73.95677447319031
                  }
                ],
                "postalCode": "11249",
                "cc": "US",
                "city": "Brooklyn",
                "state": "NY",
                "country": "United States",
                "formattedAddress": [
                  "111 N 12th St (at Wythe Ave)",
                  "Brooklyn, NY 11249",
                  "United States"
                ]
              },
              "verified": false,
              "stats": {
                "checkinsCount": 3253,
                "usersCount": 2517,
                "tipCount": 62
              },
              "url": "http://westlightnyc.com",
              "rating": 9.1,
              "ratingColor": "00B551",
              "ratingSignals": 353,
              "allowMenuUrlEdit": true,
              "beenHere": {
                "lastCheckinExpiredAt": 0
              }
            },
            "index": 0,
            "isNew": true
          },
         //..
        ]
      },
      "completedCount": 0
    }
  }
}