Get User Lists

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 Version

string
required
The API version date as documented here; e.g. 20231010

Group

string
can be created (lists created by this user), edited (other people's lists this user has edited), followed (lists this user follows), friends (lists from this user's friends), and suggested (lists relevant to the user's current location).

ll

string
The latitude/longitude around which to retrieve place information. This must be specified as latitude,longitude (e.g., ll=41.8781,-87.6298). Required in order to receive the suggested group.

Limit

int32
Number of results to return, up to 200.

Offset

int32
The number of results to skip. Used to page through results.

`200`

object
Successful response object containing lists created by the authenticated user.

Notifications

array of objects
Array of notification objects returned for the successful response to a request for the authenticated user's lists.

notifications
object
Array of notification objects containing information about the user's notifications.
item
object
Notification items for a user's lists.
type: string
The type of notification for a list of user's lists.

Response

object
Object containing the retrieved data for a user's lists.

lists
object
Array of lists created by the authenticated user.

Example Response

{
  "meta": {
    "code": 200,
    "requestId": "652464754421613d6b31c618"
  },
  "notifications": [
    {
      "type": "notificationTray",
      "item": {
        "unreadCount": 3
      }
    },
    {
      "type": "unconfirmed",
      "item": {
        "unreadCount": 0
      }
    }
  ],
  "response": {
    "lists": {
      "count": 3,
      "groups": [
        {
          "type": "yours",
          "name": "Your Places",
          "count": 2,
          "items": [
            {
              "id": "12345678/todos",
              "name": "My Saved Places",
              "description": "",
              "placesSummary": "Carleton Farm, Lake Stevens",
              "type": "todos",
              "user": {
                "id": "123456",
                "firstName": "John",
                "lastName": "Smith",
                "handle": "johnsmith",
                "privateProfile": false,
                "gender": "male",
                "countryCode": "US"
              },
              "editable": true,
              "public": true,
              "collaborative": false,
              "url": "/johnsmith/list/todos",
              "canonicalUrl": "https://foursquare.com/johnsmith/list/todos",
              "updatedAt": 1679427002,
              "listItems": {
                "count": 2
              },
              "photos": {
                "count": 2
              }
            },
            {
              "id": "12345678/venuelikes",
              "name": "My Liked Places",
              "description": "",
              "placesSummary": "Snohomish Bakery, Lucky Dragon - Chinese Restaurant, Ixtapa, Carleton Farm",
              "type": "liked",
              "user": {
                "id": "123456",
                "firstName": "John",
                "lastName": "Smith",
                "handle": "johnsmith",
                "privateProfile": false,
                "gender": "male",
                "countryCode": "US"
              },
              "editable": true,
              "public": true,
              "collaborative": false,
              "url": "/johnsmith/list/venuelikes",
              "canonicalUrl": "https://foursquare.com/johnsmith/list/venuelikes",
              "updatedAt": 1695750924,
              "listItems": {
                "count": 7
              },
              "photos": {
                "count": 4
              }
            }
          ]
        }
      ]
    }
  }
}