API overview

The Eebz API puts retailer listing data (prices, availability and product details) straight into your own systems, such as a data warehouse or a BI tool.

Authentication

Each request needs your organisation's API token. Admins create it in Settings › Organisation › General › Export API, with Create token. The same tab shows the request URL for your organisation and how to send the token with it.

Keep the token private. Anyone who has it can request your organisation's data.

A 401 response means the token is missing or invalid.

API settings

The Export API tab also holds the settings that apply to every request:

• Territory IDs: each of your territories with its ID. The API calls territories geographies, so these are the values for geography_ids.
• Retailer selection: the user whose retailer importance ratings the API uses. Needed before a request can filter by retailer_importance.
• API response fields: the fields returned when a request doesn't name its own. Leave them all unselected to return every field.
• Customised API references (optional): your own references for the data.

A first request

Send a POST request to the request URL shown in the Export API tab, with this JSON body:

{
  "geography_ids": [1]
}

This returns today's listings for one territory. Replace 1 with a territory ID from the Export API tab. See retailer listings for every parameter.

Limits

• Requests are limited per hour. Over the limit, the API returns hourly_api_limit_exceeded.
• A request sent while an earlier one for your organisation is still running returns request_already_in_progress.
• By default a live request returns up to 50,000 results and a historic request up to 5,000. Use limit and page to page through larger sets.

Reference

• Retailer listings: the endpoint, its parameters and the response shape
• Response fields: every field a listing can return
• Error codes: what each error means

For how the API fits with feeds, the app and your data stack, see integrations.