# Filtering When querying an endpoint to return multiple results back, you can use query string parameters to filter the results that you are getting back. Shippo currently supports a [results](#results) parameter and some [date filtering](#date-filtering) parameters (only currently supported on the Shipments endpoint). By default, you will only get 5 results back if you do not specify a `results` query string parameter. Note If you do not specify a `results` query string parameter, the Shippo API will only return a certain number of results. The default number of results is subject to change and depends on the resource you are calling. Many resources, such as shipments, transactions, and orders return 25 by default. Use a `results` query string parameter less than 200. A `results` query string parameter greater than 200 will cause your results to be truncated. ## Results The response will be paginated by the number specified in the `results` query string parameter. For example, for carrier accounts, by default you would only see 5 per page, with a `next` field indicating if there is another page of results. A `previous` field will give any previous pages if you're not currently looking at the first page. ## Example URL: `https://api.goshippo.com/carrier_accounts/?results=10` Response: ```json { "next": null, "previous": null, "results": [ { "carrier": "parcelforce", "object_id": "bef77ddbd2a5455eba8fcd4511eef645", "object_owner": "shippotle@shippo.com", "account_id": "shippo_parcelforce_account", "parameters": {"expresslink_password": "******"}, "test": true, "active": true, "is_shippo_account": true, "metadata":"" }, { "carrier": "usps", "object_id": "2da62634606540c082f3612afe95ecae", "object_owner": "shippotle@shippo.com", "account_id": "shippo_usps_account", "parameters": {"is_commercial": false}, "test": true, "active": true, "is_shippo_account": true, "metadata": "" }, { "carrier": "deutsche_post", "object_id": "595d9cb0c0e14497bf07e75ecfec6c6d", "object_owner": "shippotle@shippo.com", "account_id": "shippo_deutsche_post_account", "parameters": [], "test": true, "active": true, "is_shippo_account": true, "metadata": "" }, { "carrier": "uber", "object_id": "fd7f11a74c8847778fe41fed06b7fdd4", "object_owner": "shippotle@shippo.com", "account_id": "shippo_uber_account", "parameters": [], "test": true, "active": true, "is_shippo_account": true, "metadata": "" }, { "carrier": "dhl_express", "object_id": "3d05ffe6076741228dfea04385050c0d", "object_owner": "shippotle@shippo.com", "account_id": "shippo_dhlexpress_account", "parameters": [], "test": true, "active": true, "is_shippo_account": true, "metadata": "" }, { "carrier": "fedex", "object_id": "86a7793d3788422a8169cfae9c87ed26", "object_owner": "shippotle@shippo.com", "account_id": "86753099", "parameters": { "meter": "112233445", "smartpost_id": 5531 }, "test": true, "active": true, "is_shippo_account": false, "metadata": "" }, { "carrier": "dhl_germany", "object_id": "0bff0a09251d478cb919ead06709d96c", "object_owner": "shippotle@shippo.com", "account_id": "2222222222", "parameters": { "default_participation_code": "01", "business_customer_portal_password": "pass", "business_customer_portal_username": "2222222222_01", "tracking_password": "", "tracking_account": "" }, "test": true, "active": true, "is_shippo_account": false, "metadata": "" }, { "carrier": "fedex", "object_id": "8d6dbc109aaf4bb983d534f1556ddc16", "object_owner": "shippotle@shippo.com", "account_id": "86753098", "parameters": { "meter": "112233446", "smartpost_id": 5531 }, "test": true, "active": true, "is_shippo_account": false, "metadata": "Test Account" }, { "carrier": "canada_post", "object_id": "518402beb1f24e608af7be9d85a0f71b", "object_owner": "shippotle@shippo.com", "account_id": "3f937e0b21ef06f7", "parameters": { "payment_method": "CreditCard", "api_password": "secure_p@$$w0rd", "contract_id": null, "is_platform_account": true, "customer_number": "0086753098" }, "test": true, "active": true, "is_shippo_account": false, "metadata": "" }, { "carrier": "ups", "object_id": "2716480a9d7b4b31837c0dacd7d481f3", "object_owner": "shippotle@shippo.com", "account_id": "shippotle", "parameters": { "cost_center": "", "password": "secure_p@ssw0rd", "account_number": "SH1PP0", "usps_endorsement": null, "surepost": "" }, "test": true, "active": true, "is_shippo_account": false, "metadata": "" } ] } ``` You can see in the above response the amount of carrier accounts happen to line up with the amount we requested back, but if we requested 7 results, there would only be 7 carriers in the response with a url in the `next` field. ## Date filtering When querying the [Shipments endpoint](/shippoapi/public-api/shipments) you can have an additional way to filter results by limiting the date range. We expect a date formatted to the ISO 8601 standard, and you can see some example below of what that looks like. You can retrieve any 90 day range (or smaller) of shipments by using the following query string parameters: - `object_created_gt` -- object(s) created greater than a provided date time - `object_created_gte` -- object(s) created greater than or equal to a provided date time - `object_created_lt` -- object(s) created less than a provided date time - `object_created_lte` -- object(s) created less than or equal to a provided date time Date format examples: - `"2017-01-01"` - `"2017-01-01T03:30:30"` or `"2017-01-01T03:30:30.5"` - `"2017-01-01T03:30:30Z"` ## Example URL: `https://api.goshippo.com/shipments/?results=10&object_created_gte=2017-08-01T00:00:00&object_created_lte=2017-08-31T00:00:00` ```json { "next": "https://api.goshippo.com/shipments/?object_created_gte=2017-08-01T00%3A00%3A00&object_created_lte=2017-08-31T00%3A00%3A00&results=10&page=2", "previous": null, "results": [ { "address_from": {...}, "address_return": {...}, "address_to": {...}, "carrier_accounts": [], "customs_declaration": null, "extra": [], "messages": [], "metadata": "", "object_created": "2017-08-03T23:21:20.884Z", "object_id": "4a310649f51f4b15aeeabb6457b50d04", "object_owner": "shippotle@shippo.com", "object_updated": "2017-08-03T23:22:28.553Z", "parcels": [...], "rates": [...], "shipment_date": "2017-08-03T23:22:28.553Z", "status": "SUCCESS", "test": true }, { "address_from": {...}, "address_return": {...}, "address_to": {...}, "carrier_accounts": [], "customs_declaration": null, "extra": [], "messages": [], "metadata": "", "object_created": "2017-08-05T21:11:46.431Z", "object_id": "76055268f88c46e8b337e2058bc61186", "object_owner": "shippotle@shippo.com", "object_updated": "2017-08-05T21:11:46.431Z", "parcels": [...], "rates": [...], "shipment_date": "2017-08-05T21:11:46.431Z", "status": "SUCCESS", "test": true } ] } ``` Note The format of the `page` query parameter in the `next` and `prev` fields is subject to change and specifically may not necessarily be an integer. The above response includes all shipments created on or after August 1, 2017 up to and including August 31, 2017. If `object_created_gt` and `object_created_lt` were used, it would only retrieve shipments *between* those dates. You can use any combination of `object_created_gt`/`object_created_gte` and `object_created_lt`/`object_created_lte` to filter how you need. You just need to be sure that the date range is 90 days or less.