Feed optimization
Location feeds may contain a large number of records, especially when retrieving data for all supported countries. To reduce download size and bandwidth usage, you can use two optimization options:
- Brotli compression reduces the size of the downloaded feed.
- The
countryparameter limits the response to records from a single country.
These options can be used independently, but provide the greatest benefit when combined. Together, they can significantly reduce transfer size and help clients operating under feed size limits.
Enable Brotli compression
Send the standard HTTP request header:
Accept-Encoding: br
The server responds with Brotli-compressed content:
Content-Encoding: br
Vary: Accept-Encoding
Your HTTP client must automatically, or explicitly, decompress the response before parsing the JSON.
- cURL
- Python
curl --compressed \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept-Encoding: br" \
"https://pickup-point.api.packeta.com/v5/__API_KEY__/branch/json"
import requests
response = requests.get(
"https://pickup-point.api.packeta.com/v5/__API_KEY__/branch/json",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Accept-Encoding": "br",
},
)
response.raise_for_status()
data = response.json()
--compressed tells cURL to request compression and decompress the response.
Use a Brotli-capable HTTP stack if your client does not support Brotli natively.
Select a country
Add the optional country query parameter to these feeds:
- Packeta PUDO (
/branch) - Packeta Z-BOXes (
/box) - External carrier points (
/carrier_point)
Use an ISO 3166-1 alpha-2 country code. The value is case-insensitive and normalized to uppercase.
The carrier list does not support the country filter.
Combined example
curl --compressed \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept-Encoding: br" \
"https://pickup-point.api.packeta.com/v5/__API_KEY__/branch/json?country=CZ"
Always combine the country filter with Accept-Encoding: br when the client has a feed-size limit.
The largest measured per-country feeds were approximately 600 kB for Branches in CZ and 1.4 MB for carrier points in Poland.
Validation rules and technical notes
- Omitting
country, or sending an empty or whitespace-only value, returns the complete feed. - A value that is not exactly two ASCII letters (for example
CZEorC1) returns HTTP 400. - A valid country that is not enabled for the API key returns HTTP 400:
Country 'XX' is not available for this API key. - For carrier points,
countrycan be combined withids[]; both filters apply. - Compressed responses are chunked and do not contain
Content-Length. Do not require that header. - If both
brandgzipare accepted, the server prefers Brotli.
The full, unfiltered carrier point feed remains above 5 MB even with Brotli compression (approximately 6.3 MB). Use the country filter to keep individual downloads below the 5 MB limit.
Response and error handling
| Status | Meaning | Client action |
|---|---|---|
| 200 | Feed returned successfully. | Decompress, then parse the JSON. |
| 400 | Invalid country format or country unavailable for the API key. | Use a two-letter ISO code and verify client country settings. |
| 401 | Invalid or missing API key. | Verify the API key. |
| 404 | Unknown feed or resource type. | Verify the endpoint and feed name. |
| 415 | Unsupported action or response format. | Use the supported JSON action/format. |
Implementation checklist
- Use HTTPS and send the API key.
- Send
Accept-Encoding: br. - Ensure the HTTP client can decompress Brotli.
- Add the
countryquery parameter using a two-letter ISO 3166-1 alpha-2 country code. - Handle HTTP 400, 401, 404, and 415 responses.
- Do not depend on
Content-Lengthfor compressed responses.