Overview, explanation and pointers to the API documentation.

The Omnia 2.0 API (also known as the Pricemonitor API) gives access to the superpowers behind the Omnia Retail platform.

The Omnia 2.0 app and the Pricemonitor app are the main consumers of this API, but we also have endpoints available to customers to integrate the API directly with their own systems.

These are common API operations for customers to integrate Omnia with their own systems:

• Retrieve market data
• Retrieve price recommendations
• Manage your product assortment
• Provide offers for custom sources

Retrieve market data via API

Use this operation to retrieve the newest offers in the market for products for a given time range. It supports returning paged results. We recommend to retrieve with a page size of at most 1,000 products.

Retrieve price recommendations via API

Use this operation to retrieve the price recommendations for all products for a specified timerange. It supports returning paged results.

Query products via API

Use this operation to retrieve products via a query. It supports returning paged results. We recommend to retrieve with a page size of 10,000 products.

Manage your product assortment

Use this operation to upload your product assortment in JSON format. We recommend that you provide your product data in multiple parts via sequential requests to this endpoint. After providing all data, you need to delete the old data via this operation by specifying a timestamp just before your import.

If you cannot use the JSON format, as a fallback, we support uploading your product assortment to our system in CSV format via this operation.

Provide offers for custom sources

Use this operation to provide external offers for your products to our system.

API endpoints can potentially return a lot of items. Returning all data as one response to one request can overload the server, the database or the client. Returning all items may even be unnecessary when the client is only interested in the top N entries. So API operations that could return a lot of data support pagination. The pagination approach used in the latest version of API operations is described here.

Pagination basics

Operations that support pagination:

• Return a subset of all matching items based on parameters in the request. Such a subset is called a page.
  • The limit parameter defines the maximum number of items returned per page.
  • The start parameter defines which page is returned.
• Return the requested page as an array within a data object within the response.
• Can return all matching items by subsequently requesting multiple pages.

There are no subsequent matching items if the number of items in a response is smaller than the requested limit.

limit parameter

This parameter defines how many items are returned at most in a singe response. This is also called the page size.

The API documentation states the range that is allowed to be specified by the client.

start parameter

This parameter defines from which item in the total result set this request wants data to be returned. It basically defines what page should be returned. The index of the first item is 0. If the value of start is beyond the number of matching items, an empty data array is returned in the response.

Pagination itself only works when the entries have a stable sorting. This is the responsibility of the API.

Example of paginated requests

To request items with a page size of 1000, these are the pagination parameter values to be used for subsequent requests

So the values for each subsequent request can be calculated by start = previous start + limit. All the other parameters of the API request must keep the same value to get stable sorting for a stable total result set.

A response looks like this:

{
   "data": [
      <item 1>,
      <item 2>,
      ...
   ]
}

The client must compare the number of items in the data array with the used limit parameter. If they are equal there is likely a next page. If the number of items returned is less than the page size, there is no next page.

Note: In rare cases there is no next page even though the response has no less than a page size of items. E.g. when there are 2000 total items and using a page size of 1000. Here the client will make a request with start=1000 and limit=1000. The response for this 2nd page request will have 1000 items. Then the client can't know in advance if there are further pages and it has to make an additional request. This third page request will return an empty array.

There are two authentication methods supported:

• For API integration with other systems basic authentication is used.
• The Omnia 2.0 application uses JWT bearer tokens.

Operations to manage your products.

We have two options: Either you provide the products as JSON or as CSV. The product import via JSON is recommended.

Notes:

• When importing products, you need to provide an unique product identifier. We only allow importing products when they can be uniquely identified. In the very past we solely relied on GTIN for that, but not all customers have a GTIN. So we introduced the generic concept of the unique product identifier.
• When importing products, you can additionally provide tags. These tags are key/value pairs (custom fields) which can be used to categorize your products: E.g. you could add the brand of the product.
  The tag names need to be unique and non-empty.
• In some endpoints we use caching for up to 5 minutes. So your newly imported products might need up to 5 minutes to get visible.
• Timing is important: It's recommended to import products during a period when no monitorings are scheduled. Otherwise, the monitoring does not cover the most recently added products. A subsequent monitoring run will cover the previously added products.

To get the most value out of the Omnia 2.0 insights dashboards, we recommend to include the following tag-keys in your imports. These product attributes can be used to drill-down into market and pricing insights.

Notes:

• These fields are not mandatory for a successful import. They are optional, but recommended, to get the most value out of the insights in the UI of Omnia 2.0. If you intend to use them in the recommended way
• The keys for the tags are case sensitive, so specify exactly as above.

The preferred way to import products via API is via JSON.

This operation adds products to our system using upsert (insert or update). It needs to be used in conjunction with a timestamp-based product deletion operation.

The delete makes sure that old products, which are not part of your assortment anymore, are dropped from the system.

Typical usage pattern:

1. Remember the current time in UTC
2. Add products in chunks. Recommended chunk size: 1,000 products
3. Delete old products that are not needed in the system anymore by the timestamp from step 1 minus some extra buffer, e.g. one minute.

In order to provide products to our system you can send a CSV file via this operation. This endpoint deactivates all current products and activates the ones which are provided via CSV.

This creates a "task" at our side. Tasks are processed asynchronously. Typically, a big product import with 500K products takes 5-10 minutes. The mentioned endpoint returns a task id and a url where you can check the task state. Possible task states are: pending, executing, failed and succeeded. The last two states are representing a completed task. The task itself contains more details about how many products could get imported, which ones failed plus a preview failure list.

When the product import successfully completed then the previously imported products have been deleted and only the ones which you have provided via CSV file are active in our system.

Use this operation to retrieve products via a query you specify in the request. It supports returning paged results. We recommend to retrieve with a page size of up to 10,000 products.

Use the query operation and just omit the query filter in the request. Results are paginated. A page size of at most 10,000 is recommended.

Our system uses internal product ids that are distinct from your products ids. These internal product ids are sometimes referred to as pricemonitor product ids.

Often API operations require internal product ids to be specified. So you may need to map your product id onto our internal product id.

There are two options:

• Either you store the internal product ids after importing products into our system. The import operation returns the internal product ids for each imported product.
• Or you map product ids on the fly when you need to by querying specifying your product ids in the query. It's recommended to specify 1,000 product ids at once.

Operations to get price recommendations calculated by our system.

Note:

1. Internally the system calculates a price recommendation for every domain
2. As aggregation the system then provides the cheapest price recommendation

Within the price recommendations we are providing a field called relevantDomain. This field contains from which domain the price recommendation originates.

You can get all price recommendations via this operation.

It's a paginated endpoint, so you have to request multiple pages. See pagination. Recommended page size is 1000.

It's important that you define a timerange (by providing startTime and endTime parameters) in order to guarantee a stable pagination. This endpoint returns the most recent price recommendations per product and domain: This means that price recommendations from older price calculation runs within the provided timerange are ignored.

Operations to get and manage offers.

Use this operation to provide external offers for your products to our system. This operation to add offers in bulk can be used instead of the monitoring by our system of domains for external offers.

This operation needs the internal product ids in our system. See how to determine internal product ids.

Here is an example of a JSON body to provide one offer for one product via API.

[{
    "productId": "67784570",
    "creationDate": "2024-06-11T00:15:07.099Z",
    "domain": "google.de",
    "offers": [{
        "vendorName": "amazon.de",
        "vendorDomainId": 1,
        "url": "https://www.amazon.de/-/en/dp/013142467X/",
        "price": 58.84,
        "deliveryCosts": 9.95,
        "currency": "EUR",
        "id": "636354d0-c865-4c56-84b3-bd9172e826aa",
        "productName": "Test item",
        "attributes": [{
            "key": "size",
            "value": "L"
        }],
        "maxDeliveryHours": 48,
        "minDeliveryHours": 12,
        "retrievalDate": "2024-06-11T10:50:45.659Z",
        "availability": true
    }]
}]

Use this operation to get all offers for a contract. It's a paginated endpoint, so you have to scroll through all offers.

It's important that you define a timerange (by providing startDate and endDate parameters) in order to guarantee a stable pagination.

This endpoint returns the most recent offers per product and domain: This means that offers from older monitoring runs within the provided timerange are ignored.

For continuously getting market data we recommend the following usage pattern:

Get the offers for the last 15 minutes with a time offset of 15 minutes.

Note: The time offset is important since offers are not immediately visible via the API. Sometimes there is a slight delay in offer storing.

Manage your data-feeds.

Operations to store log messages in our system.

You could integrate this API in your own system and publish the integration logs to our system so that Omnia Retail could analyze them.

Company management related endpoints.

Manage your orders.