Pagination

API Semantics

Pagination

GraphQL allows for different implementations of paginating through a list of objects. The Pandora GraphQL API makes use of cursor-based pagination, which is recommended by GraphQL since it allows for more flexibility on the client side. To allow for flexible integration, it also has offset available. Offset can be used instead of the cursor to define from where results should be returned in the result set.

The Pagination type is used as a parameter for queries returning lists of items. Some queries extend this type to allow you to sort the results based on a specific criteria.



type Pagination {
  limit: Int
  offset: Int
  cursor: String
}

limit: the amount of items you wish to receive, max of 50
offset: the zero-based offset from which to return items in the result set (ignored if a cursor is passed)
cursor: the id of the item you wish to start from (a string, if omitted it will start from the beginning)

The search query is an example of one that returns a list of items and thus includes pagination:

GraphQL 1
cURL 2



{
  search(types: [AR], query: "90s Pop Radio", pagination: { limit: 2, cursor: "NQ==" }) {
    cursor
    items {
      type
      ... on Artist {
        name
      }
    }
  }
}

* Add your OAuth bearer token to the Authorization header



curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"operationName":null,"variables":{},"query":"{ search(types: [AR], query: \"90s Pop Radio\", pagination: {limit: 2, cursor: \"NQ==\"}) { cursor items { type ... on Artist { name }}}}"}'

The response would contain the cursor to identify the offset for the current set of data.



{
  "data": {
    "search": {
      "cursor": "Nw==",
      "items": [
        {
          "type": "AR",
          "name": "Enrique Iglesias"
        },
        {
          "type": "AR",
          "name": "Selena"
        }
      ]
    }
  }
}

The cursor can then be used as an offset ID to retrieve the next 2 items:

GraphQL 1
cURL 2



{
	search(types: [AR], query: "90s Pop Radio", pagination: { limit: 2, cursor: "Nw==" }) {
    cursor
    items {
      type
      ... on Artist {
        name
      }
    }
  }
}

* Add your OAuth bearer token to the Authorization header



curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"operationName":null,"variables":{},"query":"{ search(types: [AR], query: \"90s Pop Radio\", pagination: {limit: 2, cursor: \"Nw==\"}) { cursor items { type ... on Artist { name }}}}"}'

Similarly, offset can be used to paginate through search results. A normal search, with limited results, will look like this:

GraphQL 1
cURL 2



{
  search(types: [AR], query: "90s Pop Radio", pagination: { limit: 4 }) {
    items {
      type
      ... on Artist {
        name
      }
    }
  }
}

* Add your OAuth bearer token to the Authorization header



curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"operationName":null,"variables":{},"query":"{ search(types: [AR], query: \"90s Pop Radio\", pagination: {limit: 4}) { items { type  ... on Artist {  name  }}}}"}'



{
  "data": {
    "search": {
      "items": [
        {
          "type": "AR",
          "name": "The Goo Goo Dolls"
        },
        {
          "type": "AR",
          "name": "Matchbox Twenty"
        },
        {
          "type": "AR",
          "name": "Third Eye Blind"
        },
        {
          "type": "AR",
          "name": "Hootie & The Blowfish"
        }
      ]
    }
  }
}

Using the offset parameter, the same search query will return these results:

GraphQL 1
cURL 2



{
  search(types: [AR], query: "90s Pop Radio", pagination: { limit: 4, offset: 2 }) {
    items {
      type
      ... on Artist {
        name
      }
    }
  }
}

* Add your OAuth bearer token to the Authorization header



curl 'https://ce.pandora.com/api/v1/graphql/graphql' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"operationName":null,"variables":{},"query":"{  search(types: [AR], query: \"90s Pop Radio\", pagination: {limit: 4, offset: 2}) {  items {  type  ... on Artist {  name  }}}}"}'



{
  "data": {
    "search": {
      "items": [
        {
          "type": "AR",
          "name": "Third Eye Blind"
        },
        {
          "type": "AR",
          "name": "Hootie & The Blowfish"
        },
        {
          "type": "AR",
          "name": "Maná"
        },
        {
          "type": "AR",
          "name": "Ricardo Arjona"
        }
      ]
    }
  }
}