Paginating Lists via the API

The API can return lists of Batches, ScanForms, Shipments, and Trackers over a given period of time, however, the number of results returned on one call is limited. For example, when retrieving a list of shipments the returned number limit is 100, but we can retrieve more shipments using pagination methods supported by the API. 

To accomplish this you'll need to specify a starting date and a page size for the first response and then loop until no more data is returned. The API returns data according to item ID and the before_id parameter is used to get the next page, by setting it to the last ID seen.

Example Python 3.x code:

import easypost
import os

easypost.api_key = "EASYPOST_API_KEY"

# window cannot be more than 31 days
start_datetime = '2020-05-01T00:00:00Z'
end_datetime = '2020-05-31T23:59:59Z'

# these are the objects that support retrieval and pagination
# comment out the types you do not want to retrieve
for key, obj_type in (
                      ('batches', easypost.Batch), 
                      ('scan_forms', easypost.ScanForm), 
                      ('shipments', easypost.Shipment), 
                      ('trackers', easypost.Tracker),
                      ):

    # make our initial query
    data_obj = obj_type.all(start_datetime=start_datetime, end_datetime=end_datetime, page_size=100)
    
    # get the list of items returned from the query
    data = data_obj.get(key)

    # create list to gather our results in
    results = []

    # determine if we have additional data; used for the loop below
    has_more = data_obj.has_more
    
    while has_more:
        # store the data we just retrieved
        for item in data:
            results.append(item)

        # see if we have additional data available
        has_more = data_obj.has_more
        
        # continue to query the next page if we have additional data, 
        # setting the `before_id` parameter to the last ID seen
        if has_more:
            data_obj = obj_type.all(start_datetime=start_datetime, end_datetime=end_datetime, page_size=100, before_id=results[-1].id)
            data = data_obj.get(key)

    # ensure that we get the data when we're at the end
    for item in data:
        results.append(item)

    # ensure that the results are returned in ascending order
    results.sort(key=lambda x: x.created_at)

    # print out our results; the type and number returned
    # along with the created_at data and item ID
    print(key, len(results))
    for i in results:
        print('\t' + f'{i.created_at} {i.id}')
    if results:
        print()