Sometimes Socrata API requests will return a large number of results. Rather than retrieve them all at once, which may affect your application’s performance, you can use paging to retrieve the results in batches. Often an application will show the first few results, and then only load the next batch of results when the user has taken an action, such as clicking a Next button or scrolling to the bottom of a list.
Paging is accomplished through two query parameters: $limit and $offset. Note that using paging is entirely optional: if you do not specify the $limit and $offset parameters, then the defaults will be used.
| Query Parameter | Description | Default Value | Maximum Value |
|---|---|---|---|
$limit |
The number of results to return | 1000 | 2.0 endpoints: maximum of 50,000; 2.1: unlimited » |
$offset |
The index of the result array where to start the returned list of results. | 0 | N/A |
$order clause or at a minimum $order=:id. That will guarantee that the order of your results will be stable as you page through the dataset.
The following example returns a large number of earthquake results in JSON format:
https://soda.demo.socrata.com/resource/earthquakes.json
If we were building a mobile application that only had room for 5 results on a page, we might make our first call to get the first 5 results as follows:
https://soda.demo.socrata.com/resource/earthquakes.json?$limit=5&$offset=0&$order=earthquake_id
Then, if the user clicked Next, we would retrieve the next five results with this request:
https://soda.demo.socrata.com/resource/earthquakes.json?$limit=5&$offset=5&$order=earthquake_id