CartrouteHow does pagination work?
Search returns at most limit products (1 to 25, default 10) and a next_cursor. Pass that value back as cursor, unchanged and with the same other parameters, to get the next page. On the last page next_cursor is null. Each page is a separate metered call.
How do I fetch the next page?
curl "https://cart-route.com/api/v1/search?q=laptop&limit=5" -H "Authorization: Bearer $CARTROUTE_API_KEY"
# ... "next_cursor": "eyJvIjo1fQ", "links": {"next": "https://cart-route.com/api/v1/search?q=laptop&cursor=eyJvIjo1fQ"}
curl "https://cart-route.com/api/v1/search?q=laptop&limit=5&cursor=eyJvIjo1fQ" -H "Authorization: Bearer $CARTROUTE_API_KEY"
How do I iterate every page?
import os
import requests
def search_all(q, **filters):
params = {"q": q, "limit": 25, **filters}
headers = {"Authorization": f"Bearer {os.environ['CARTROUTE_API_KEY']}"}
while True:
body = requests.get("https://cart-route.com/api/v1/search", params=params, headers=headers, timeout=15).json()
yield from body["results"]
if not body.get("next_cursor"):
return
params["cursor"] = body["next_cursor"]
Should I paginate at all?
Usually not. Results are ranked, so the first page holds the best matches; an agent answering "where should I buy X" rarely needs more than 5. Narrow the query or add filters before paging, which costs fewer credits than paging through broad results.
What makes a cursor invalid?
Editing it, or using a value from another source. An invalid cursor returns 422 validation_error with param: "cursor" and is not charged. Cursors do not expire, but results can shift between pages as prices change, because ranking is recomputed on every call.