Retrieve statistical data via API

You can create statistical reports in the following different ways:

Use Opter's statistics API to retrieve optional statistical data from Opter and then create statistical reports yourself outside Opter.

You can programme a solution where you call Opter's statistics API and then receive the results and present the statistics as you wish. You can automate the flow so that the desired statistical information is retrieved from Opter as often as you wish. For example, if the statistics are to be presented on a dashboard, you may want to retrieve statistics once every hour.
Manually take out a statistical report when you wish. More information can be found in Statistical reports.

The statistics API works like this

Using the statistics API, you can retrieve data/information related to transport orders that is available in Opter, such as delivery time precision. The information returned by the statistics API is the "raw data"/basic data from the database in Opter.
The user of the statistics API needs an API key (see Step 2: Create an API key below).
When you call the API, you get back all the data you chose to retrieve in the same call. (The statistical data is not divided into smaller parts, no pageing takes place).
When you call the API, you get the data back as it is at that moment in the database in Opter.
You can retrieve data as often as you like. However, we recommend that you do not collect more often than necessary for your purpose.
When calling the API, it is mandatory to specify the period for which you want the statistics (dateFrom and dateTo) and the date type on which the statistics should be based (dateType). For more information, see the table Selecting the type of date on which to base the statistical data below.

Step 1: Planera

The steps below provide instructions on how to use the statistics API, but we recommend that you do the following first:

Decide what you want to achieve, i.e. what do you want to get out and why.
Decide how often the statistical data will be retrieved from Opter.

For example, if you want to present the statistics on a dashboard, you may want to retrieve the statistics data once every hour. If you want to use the statistics for follow-up at the end of each day, you can download the statistical data at the end of each day.
Decide who will have access to the statistics API. Anyone who accesses the statistics API will have access to all data, including information on customers, prices, invoices, etc.

Tip

If you have any questions, please contact the EDI team at .
To retrieve statistical data on CO2 emissions, see Climate impact of CO2 emissions in grams, pricing weight.

Step 2: Create an API key

Note:

Anyone who accesses the statistics API will have access to all data, including information on customers, prices, invoices, etc. There is no way to restrict access (for example, to exclude information on prices).

The user of the statistics API needs an API key. Proceed as follows:

Click on Settings > API access (and the tab General).
To create a new user, click on and enter Name.

The API key field displays the API key that has been created.
In the Description field, you can describe what the user will have access to.
Click on the Access tab.
Double-click on Statistics in the Excluded list and Statistics will be moved to the Included list.

This means that the user can access all statistical data in Opter via the statistics API, using the API key.
Click on to save all changes.

Step 3: Go to the swagger documentation

The Swagger documentation for the statistics API can be found at the same URL as the customer web, but with "/api" at the end:
- If you are running Opter Cloud:
  
  https://<ert företagsnamn>.opter.cloud/api/index.html
  
  Example: If your company name in Opter is "budfirman" and the country is Sweden, use https://budfirmanse.opter.cloud/api/index.html
- If you have your own server:
  
  https://<your company name or IP address>.<country>/api/index.html
  
  Example: If your company name in Opter is "budfirman" and the country is Sweden, you use
  
  https://budfirman.se/api/index.html eller 123.45.678.901/api/index.html
If you cannot find the swagger documentation for the statistics API, please contact the EDI team at .
In the top right-hand corner of the website, there is a drop-down menu Select a definition. Select "Opter API v1".

Using the data model (optional)

If you want to import the API into a tool such as Postman, you can find the data model for the API at the top of the swagger webpage.

Try using the API (optional)

If you want to test using the API, you can do so on the swagger website or use a test programme such as Postman.

If you want to try calling the statistics API on the swagger website and see the results, do this:

In the top right-hand corner of the website, there is a drop-down menu Select a definition. Select "Opter API v1" from the drop-down menu.
Click on Authorize. Copy the API key from the API access window in Opter, paste it into the Value field and click Authorize. Now it says Authorized in the window. Click on Close.

(You created the API key in Step 2: Create an API key above.)
Scroll down to Statistics and click on GET.

All parameters ("queries") are displayed.
Click on the Try it out button.
Select dateType (mandatory) from the drop-down menu. The meaning of the different choices is shown in the table Selecting the type of date on which to base the statistical data below.
Select the period for which you want the statistical data by choosing dateFrom (mandatory) and dateTo (mandatory).

Dates are written in the format "yyyy-mm-dd", for example "2024-08-19". If you want to enter both the date and the time, type a space between the date and the time, for example "2024-08-19 13:30".

If you only enter the date, the default time is 00:00.
Choose which statistical data you want by selecting "true" in the drop-down list for those parameters. For example, includeDeliveries and includeScans.

(The default setting is "false", which means you only need to select "true" for the parameters you want to include in the statistics data.)

Tip
Details on what data is retrieved if you select "true" for, for example, includeDeliveries and includeScans are shown further down the swagger documentation under Schemas. Click on Statistics.Delivery and Statistics.Scan. Click on "[...]" to see more details.
In the api-version field, you can choose to enter a specific version or leave the field blank if you want the latest version of the API to be used. For example, if you want to use a specific version, type "1.0" in the field.
Click on the Execute button to send the API call. The results are available at Responses.

Under Server response the result/response is displayed in JSON format. Click on the button Download to download the JSON file.

Tip
If you want to test the same API call in, for example, the Postman tool, you can copy the API call shown in the code window Curl.
If you want to test again (for example with other parameters), click on Clear next to Execute to clear under Responses. You can then call the API again by clicking on Execute and view the results.

Select the type of date on which the statistical data will be based

When calling the Statistics API, use the parameters dateFrom (from date and time) and dateTo (to date and time) to select the period for which the statistical data should be retrieved.

You use the parameter dateType to select the type of date on which the statistical data will be based as shown in the table below.

dateType	Description
TransportDate	Based on orders where Order date matches the date range. All information about those orders can be included, including invoices, scans, etc. outside the date period.
ScanDate	Based on scan lines (parcel scans or consignment note scans). All information on the orders that have scans in the selected period can be included, regardless of the order date of the orders, the invoice date of the invoices, etc. Invoices and settlements will not necessarily be complete, only those orders that have scans in the period will be included. Tip In the parameters dateFrom and dateTo it may be relevant to specify both date and time. See example below.
InvoiceDate	Based on invoices where the invoice date matches the date period. All information about orders included on the invoices can be included. This applies even if it is just an additional invoice on the order (a new item or a credit note, for example). Orders that are not on an invoice that matches the period will not be included, regardless of the order date, scan date, etc.
BillDate	Based on settlements where the settlement date matches the date period in the same way as above.
ChangeDate	Retrieves data on which orders have changed during the period. This does not only apply to changes made by opening the order, making changes and then saving it. This also applies to changes made to traffic management and apps, for example: If a driver changes the status from Picked up to Delivered in the Opter Driver app, the statistics will show that the order has changed. If you change the status in the traffic management or connect to co-loading, the statistics will show that the order has changed. Tip In the parameters dateFrom and dateTo it may be relevant to specify both date and time. See example below. For an order that has been modified during the period, the date and time when the order was last modified (during the period) is displayed. Tip You can see some more information about changes to the orders by looking at the logs in the Order log box in the order reception in Opter.

Restrictions

There is no history to follow on the order. When you call the API, Opter returns the data as it is at that moment.

However, it is possible to get statistics on which orders have been changed during a certain period, see ChangeDate above. The statistics do not show what has been changed, only the date and time the order was last changed.

Tip
You can see some more information about changes to the orders by looking at the logs in the Order log box in the order reception in Opter.
Opter provides the statistics API, but you are responsible for how the results/responses of the API calls are handled and analysed. Opter does not provide tools for that.

Example

Statistics on which orders have been changed

If you want to retrieve data on the following:

Which orders have changed during a certain date period, for example during the month of December 2024. Enter the date range in the parameters dateFrom "2024-12-01" and dateTo "2025-01-01". (If you only enter the date, the default time is 00:00.)
Which orders have changed since a certain date, up to and including so far today, for example, from "2024-07-22" to today's date and current time. Enter the date in the parameter dateFrom "2024-07-22", and the date and time in the parameter dateTo "2024-07-26 13:30" (today's date and current time).

Note:
If you do not specify a time, the default time is 00:00. This means that if you only enter (today's) date in dateTo, you will not see which orders have changed today.
Which orders have changed in the last 10 minutes.

For example, if the time is 10:20 and the date is 2024-07-26, then you enter today's date and the time that was 10 minutes ago in the parameter dateFrom "2024-07-26 10:10", and today's date and the current time in the parameter dateTo "2024-07-26 10:20".

Select "ChangeDate" from the drop-down menu dateType. (For more information, see the table above, see ChangeDate.)

Select "true" from the drop-down menu includeDeliveries.

Tip

Details on what data is retrieved if you select "true" for includeDeliveries are shown further down the swagger documentation under Schemas. Click on Statistics.Delivery and then on "[...]" to see more details. For orders that have changed during the period:

The 'id' shows the order number.
In "customerCode" the customer code is displayed.
"created" shows the date and time when the order was created.
"changed" shows the date and time when the order was last changed.

Troubleshooting

If you cannot find the statistics API in the swagger documentation, check that you have selected "Opter API v1" in the drop-down menu in the top right corner of the web page in the drop-down menu Select a definition. See picture above.
If the API key does not work, you can create a new one in the API access window on the General tab at the API key field. To create a new API key, click on New key and then on to save it. You can then use it to access the statistics API.
If you have any questions or need help with troubleshooting, please contact the EDI team at .