Přeskočit na hlavní obsah
For any questions, feel free to contact our integrations team at integrations@packeta.com

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 country parameter 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 --compressed \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept-Encoding: br" \
"https://pickup-point.api.packeta.com/v5/__API_KEY__/branch/json"
info

--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:

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"
Recommendation

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 CZE or C1) 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, country can be combined with ids[]; both filters apply.
  • Compressed responses are chunked and do not contain Content-Length. Do not require that header.
  • If both br and gzip are accepted, the server prefers Brotli.
Feed-size note

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​

StatusMeaningClient action
200Feed returned successfully.Decompress, then parse the JSON.
400Invalid country format or country unavailable for the API key.Use a two-letter ISO code and verify client country settings.
401Invalid or missing API key.Verify the API key.
404Unknown feed or resource type.Verify the endpoint and feed name.
415Unsupported action or response format.Use the supported JSON action/format.

Implementation checklist​

  1. Use HTTPS and send the API key.
  2. Send Accept-Encoding: br.
  3. Ensure the HTTP client can decompress Brotli.
  4. Add the country query parameter using a two-letter ISO 3166-1 alpha-2 country code.
  5. Handle HTTP 400, 401, 404, and 415 responses.
  6. Do not depend on Content-Length for compressed responses.