Valid from: Opter 2023.12.203

Retrieving statistical data via API

Statistical reports can be created in the following different ways:

• Use Opter's statistics API to get any statistical data from Opter and then create statistical reports outside Opter.

  You can programme a solution where you call Opter's statistics API and then receive the results and present the statistics as desired. The flow can be automated so that the desired statistical information is retrieved from Opter as often as desired. For example, if the statistics are to be presented on a dashboard, you may want to retrieve statistics once every hour.

• Manually generate a statistical report whenever desired. For more information, see Statistical reports.

The statistics API works like this

• Using the statistics API, it is possible to retrieve data/information related to transport orders that is contained in Opter, such as delivery time accuracy. 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 paging takes place).

• When you call the API, you get the data back as it is at that exact moment in the database in Opter.

• You can retrieve data as often as you like. However, we recommend that you do not retrieve it more often than is necessary for the intended 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 Select the type of date on which to base the statistical data below.

Step 1: Plan

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

1. Decide what you want to achieve, i.e. what do you want to get out and why.

2. Decide how often the statistical data shall be retrieved from Opter.

   For example, if the statistics are to be presented on a dashboard, you may want to retrieve the statistical data every hour. If you want to use the statistics for a follow-up at the end of each day, you can download the statistical data at the end of each day.

3. Decide who will have access to the statistics API. Anyone who accesses the statistics API will have access to all the data, including information on customers, prices, invoices, etc.

Step 2: Create an API key

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

1. Click on Settings > API access (and the General tab).

2. To create a new user, click on and enter Name.

   The API key field displays the API key that has been created.

3. In the Description field, describe to what the user shall have access.

4. Click on the Access tab.

5. 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 the statistical data in Opter via the statistics API using the API key.

6. Click on to save all changes.

Step 3: Go to the swagger documentation

1. The swagger documentation for the statistics API is at the same URL as the customer web, but with "/api" at the end:

   • If you are running Opter Cloud:

     https://<your company name><country>.opter.cloud/api/index.html

     Example: If your company name in Opter is "courier services" and the country is Sweden, use https://courierservicesse.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 "courier services" and the country is Sweden, use

     https://courierservices.se/api/index.html or 123.45.678.901/api/index.html

   If you cannot find the swagger documentation for the statistics API, please contact the EDI team at .

2. In the top right-hand corner of the website is the Select a definition drop-down list. Select "Opter API v1".

   

Use the data model (optional)

To import the API into a tool such as Postman, the data model for the API is at the top of the swagger website.

Try using the API (optional)

If you want to test using the API, this can be done on the swagger website or by using a test program such as Postman.

To try calling the statistics API on the swagger website and see the results, proceed as follows:

1. In the top right-hand corner of the website is the Select a definition drop-down list. Select "Opter API v1" from the drop-down list.

   

2. Click on Authorize. Copy the API key from the API access window in Opter, paste it into the Value field and click on Authorize. Now it says Authorized in the window. Click on Close.

   (You created the API key in Step 2: Create an API key above).

3. Scroll down to Statistics and click on GET.

   

   All the parameters ("queries") are displayed.

4. Click on the Try it out button.

5. Select dateType (mandatory) from the drop-down list. What the different choices mean is shown in the table Select the type of date on which to base the statistical data below.

6. Select the period for which the statistical data is required by choosing dateFrom (mandatory) and dateTo (mandatory).

   Dates are written in the format "yyyy-mm-dd", for example "2024-08-19". 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 only the date is entered, the default time of 00:00 is used.

7. Choose which statistical data you want by selecting "true" for those parameters in the drop-down list. For example includeDeliveries and includeScans.

   (The default setting is "false", which means "true" only needs to be selected for the parameters that are to be included in the statistical data).

   Tip

   Details on what data is retrieved if "true" is selected for, for example, includeDeliveries and includeScans are shown further down in the swagger documentation, under Schemas. Click on Statistics.Delivery and Statistics.Scan. Click on "[...]" to see more details.

   

8. In the api-version field, a specific version can be entered or the field can be left blank to use the latest version of the API. To use a specific version, type for example "1.0" in the field.

9. Click on the Execute button to send the API call. The results are available under Responses.

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

   Tip

   To test the same API call in, for example, the Postman tool, copy the API call shown in the Curlcode window.

10. To test again (for example with other parameters), click on Clear next to Execute to clear under Responses. The API can then be called again by clicking on Execute and viewing the results.

Select the type of date on which to base the statistical data

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

The dateType parameter is used 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 period. All the information about those orders can be included, including invoices, scans, etc. that are outside the date period.
ScanDate	Based on scan rows (package scans or freight bill scans). All the information about 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 supplier bills will not necessarily be complete, only those orders that have scans in the period will be included. Tip In the dateFrom and dateTo parameters, 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 the information on orders in the invoices can be included. This applies even if there is just additional invoicing on the order (a new price item or a correction, for example). Orders that are not on an invoice matching the period will not be included, regardless of the order date, scan date, etc.
BillDate	Based on supplier bills where the crediting date matches the date period in the same way as above.
ChangeDate	Retrieves data about which orders have changed during the period. This applies not only to changes made by opening the order, making changes and then saving it. It also applies to changes made in dispatch 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 in dispatch the status is changed or a connection to a consignment is made, the statistics will show that the order has changed. Tip In the dateFrom and dateTo parameters, it may be relevant to specify both date and time. See example below. For an order that has been changed during the period, the date and time when the order was last changed (during the period) is displayed. Tip A bit more information about changes to the orders can be seen by looking at the logs in the Order log box in order reception in Opter.

Limitations

• There is no history that can be followed on the order. When the API is called, the data as it is at that exact moment in Opter is returned.

  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

  A bit more information about changes to the orders can be seen by looking at the logs in the Order log box in 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 December 2024. Enter the date period in the dateFrom "2024-12-01" and dateTo "2025-01-01" parameters. If only the date is entered, the default time of 00:00 is used.

• 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 dateFrom parameter "2024-07-22", and the date and time in the dateTo parameter "2024-07-26 13:30" (today's date and current time).

  Note:

  If you do not specify a time, the default time of 00:00 is used. This means that if you only enter (today's) date in dateTo, you will not see any orders that have been 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, you enter today's date and the time that was 10 minutes ago in the dateFrom parameter "2024-07-26 10:10", and today's date and the current time in the dateTo parameter "2024-07-26 10:20".

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

Select "true" in the includeDeliveries drop-down list.

Troubleshooting

• If you cannot find the statistics API in the swagger documentation, check that you have selected "Opter API v1" in the drop-down list in the top right corner of the website, in the Select a definition drop-down list. See the image above.

• If the API key does not work, a new can be created 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. It can then be used to access the statistics API.

• If you have any questions or need help with troubleshooting, please contact the EDI team at .

---