Pagination enables you to get more results, or offset the results you get when making multiple searches

Pagination controls how many results you receive and where in the result set to start. This is essential for building user interfaces that display results in pages or when you need to fetch large numbers of venues.

Query parameters

Pagination is controlled through two query parameters on the search endpoint:

limit

Maximum number of results to return (1-100). Defaults to 20.

offset

Number of results to skip before starting to return results. Defaults to 0.

Basic usage

Get first page (default)

const response = await fetch("/v1/search/?limit=20&offset=0");

Get second page

const response = await fetch("/v1/search/?limit=20&offset=20");

Get third page

const response = await fetch("/v1/search/?limit=20&offset=40");

Request examples

First page of results

const response = await fetch("/v1/search/?limit=20&offset=0", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "API-KEY": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    locations: [{ lat: 51.5072, lon: -0.1276 }],
    mode: { mode: "POINT", maxDistance: 1000 },
    preferences: { establishmentFilters: ["restaurant"] },
  }),
});

Second page of results

const response = await fetch("/v1/search/?limit=20&offset=0", { 
const response = await fetch("/v1/search/?limit=20&offset=20", { 
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "API-KEY": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    locations: [{ lat: 51.5072, lon: -0.1276 }],
    mode: { mode: "POINT", maxDistance: 1000 },
    preferences: { establishmentFilters: ["restaurant"] },
  }),
});

Best practice

Use reasonable limits: 20-50 results to not overwhelm your users
Implement proper error handling: Handle cases where offset exceeds total results
Show loading states: Indicate when fetching more results
Consider user experience: Don't make users wait for large result sets

Billing considerations

Currently, billing is applied assuming 20 result groups. For example; if you request 20 results, 0.006 will be charged to your account, if you requested 100 results, 0.03 will be charged to your account, if you requested 35 results, 0.012 will be charged to your account.

Pagination