Pagination

API resources support pagination for large collections. Methods include token pagination (for the entity endpoint) and offset pagination (for all others). To navigate the API efficiently, you’ll need an understanding of these methods.

Token Pagination

We utilize token pagination within the entity endpoint (relationships, possibly_same_as, and referenced_by), where payload size and dynamic item count make this the most effective method.

How it works

• Each request returns a token (e.g., next or prev) in the response.
• You can use this token in the next request to fetch the subsequent set of data.
• If there is no token in the request, our platform defaults to the first page of results.
• limit controls the number of items per page, with a maximum and default value specific to each endpoint. The typical default value is 100.

Arguments

Example

• next=qr7bvn2: Fetch the next page of relationships with a specific token.
• limit=10: Restrict the results to 10 items per page.

$
GET /entity/abc?attributes.name.limit=10&relationships.next=qr7bvn2

Offset Pagination

Offset pagination is straightforward and used when the total item count is known. It is utilized in most endpoints.

How it works

• Users fetch data based on offset (start point) and limit (number of items to return).
• offset defines the starting point by skipping a set number of items.
• limit sets the maximum items to be returned in a response.
• Metadata in the response indicates the availability of more data.

Arguments

Example

• offset=20: Begin results from the 21st object.
• limit=50: Restrict the results to 50 items per page.

$
GET /search/entity?q=China&offset=20&limit=50

Paginating Search

Search queries can return many results. Use offset pagination to manage them efficiently.

Example

• offset=100: Starts the results from the 101st object.
• limit=50: Limits the number of results to 50 per page.

$
GET /search/entity?q=China&offset=100&limit=50 HTTP/1.1
>
Accept: application/json

The API response will include information about the availability of additional data:

• The count field indicates the number of results (10,000 is the max). There may be more results in this response example.
• The next field indicates whether more results are available beyond the current page.
• Subsequent requests can adjust the offset to access further results.

1
{
2
    "offset": 100,
3
    "limit": 50,
4
    "next": true,
5
    "size": {
6
        "count": 10000,
7
        "qualifier": "gte"
8
    },
9
    "data": [...]
10
}

Paginating Entities

When working with entities in the Sayari API, you’ll find that each entity can have multiple attributes and relationships, which often leads to extensive datasets. Use token pagination to manage these results efficiently. Pagination “next” or “prev” tokens are passed as query parameters.

Example combinations

• attributes.[field].['next' | 'prev']=[string] | ?attributes.address.next=qr7bvn2
• relationships.['next' | 'prev']=[string] | ?relationships.next=qr7bvn2
• possibly_same_as.['next' | 'prev']=[string] | ?possibly_same_as.next=qr7bvn2
• referenced_by.['next' | 'prev']=[string] | ?referenced_by.next=qr7bvn2

Examples

• attributes.name.limit=10: Limits the number of name attributes to 10 per page.
• relationships.next=qr7bvn2: Uses a token to fetch the next page of relationships.
• relationships.limit=200: Sets a limit of 200 for the number of relationships per page (which is the maximum for relationships).

$
GET /entity/abc?attributes.name.limit=10&relationships.next=qr7bvn2&relationships.limit=200

The API response will include information about the availability of additional data:

• The count field indicates the number of results per attribute.
• The next & prev fields contain tokens that can used in the subsequent request to fetch the next or previous set of data.
• The limit field indicates the limit per attribute.

1
{
2
    ...
3
    "attributes": {
4
        "name": {
5
            "next": "y4rkp09",
6
            "limit": 10,
7
            "size": {
8
                "count": 18,
9
                "qualifier": "eq"
10
            },
11
            "data": [...]
12
        }
13
    },
14
    "relationships": {
15
        "next": "w98vmfd",
16
        "prev": "myvc64l",
17
        "limit": 200,
18
        "size": {
19
            "count": 1201,
20
            "qualifier": "eq"
21
        },
22
        "data": [...]
23
    },
24
    "possibly_same_as": {
25
        "limit": 100,
26
        "size": {
27
            "count": 12,
28
            "qualifier": "eq"
29
        },
30
31
        "data": [...]
32
    },
33
    "referenced_by": {
34
        "next": "84ct7eb",
35
        "limit": 100,
36
        "size": {
37
            "count": 300,
38
            "qualifier": "eq"
39
        },
40
        "data": [...]
41
    }
42
}

Paginating Records

For records that reference numerous entities, pagination is key to accessing this data in a manageable way. Records utilize offset pagination.

Example

• offset=100: Starts the results from the 101st object.
• limit=50: Limits the number of results to 50 per page.

1
GET /record/123?references.offset=100&references.limit=100 HTTP/1.1Accept: application/json`

The API response will include information about the availability of additional data:

• The count field indicates the number of results.
• The next & prev fields contain tokens that can used in the subsequent request to fetch the next or previous set of data. In the instance below, “next” is false , indicating there are no more results.
• The limit field indicates the limit returned.

1
{
2
    ...
3
    "references": {
4
        "next": false,
5
        "offset": 100,
6
        "limit": 100,
7
        "size": {
8
            "count": 140,
9
            "qualifier": "eq"
10
        },
11
        "data": [...]
12
    }
13
}

Paginating Traversals

The traversal endpoints’ response paths are paginated via offsets. Because the total number of potential matching paths is very expensive to compute, the response does not include size values. Instead, use the next boolean field to determine if there are more pages of results to return.

Example

• offset=20: Starts the results from the 21st object.

$
GET /traversal/123?offset=20&max_depth=8 HTTP/1.1Accept: application/json

The API response will include information about the availability of additional data:

• The next & prev fields contain tokens that can used in the subsequent request to fetch the next or previous set of data. In the instance below, “next” is true , indicating there are more results.
• The limit field indicates the limit returned.

1
{
2
    "offset": 20,
3
    "limit": 20,
4
    "next": true,
5
    "data": [...]
6
}