What’s here?

This page describes the Aeris AerTraffic™ System Web Services interface for retrieving Device traffic and billing data. Similar information is available via our web-based UI, AerPort™.

AerTraffic Overview

The AerTraffic 2.1 API includes the following set of APIs:

The Online Reports API provides quick reports with a feature to download a report preview and the complete report file.

The Scheduled Reports API provides the ability to create report templates with a defined frequency. The API will trigger the reports on their scheduled frequency and an email will be forwarded to the defined recipients once report generation is complete. A link will be provided in the email to allow the user to download the report.

The Trend Reports API provides various account trends including device counts, overage charges, and packet/SMS usage.

Base URLs

The URL address for the production service is shown in the table below.

[table id=89 /]

API XSD Documentation

[table id=90 /] [table id=91 /]

API Request, Headers and Parameters

AerTraffic 2.1 APIs are only available over HTTPS.

Each API access must include the appropriate API Key in the request URL as shown in the examples. The parameter name is “apiKey”.

All API must include Content-Type header with value application/json.

API Client Authentication

Every request to the API should be authorized with a valid API Key. This should be passed as a query parameter in the URLs.

There is a direct relation between the accountID and the apiKey passed in the URL. A valid apiKey but of a different account will face un-authorized Exceptions.

The API Keys are unique and secret keys. These must be saved securely and should be shared with authorized users or applications only.

Unique IDs

There are 2 sets of Unique IDs:

Request ID: Every Response will hold a unique 36-bit, alpha-numeric request ID and can be used to track the complete transaction.

Archive ID: Every report generated will be stored with a unique 36-bit, alpha-numeric archive ID.

Date Information

All dates are in Greenwich Mean Time (GMT) for input and output parameters.

Start date inputs are interpreted as “begin” dates and will return records starting with the first second of the date entered.

End date inputs are interpreted as “through” dates and will return records ending with the last second of the date entered.

The billing period calendar month also starts and stops on GMT monthly boundaries.

Report Definitionstopics

Account Reports

Account level reports provide general data for all devices in the account, or for a specified group of devices. There are three Account level reports:

Account Traffic Cost Summary Report

Formerly named Traffic Cost Summary Report

Summarizes usage and overage charges based on Pool Name or Report Group over a specified time period.

Account Devices Detail Report

Formerly named Device Detail Report

Provides a listing of all devices and device attributes within the selected Device Filters.

Account Devices Summary Report

Formerly named Device Summary Report

Provides a device count based on the group of devices selected.

Device Reports

Device level reports allow you to obtain detailed data for a specific device or group of devices. There are four Device level reports:

Daily Device Traffic Usage Report

Formerly named: Daily Traffic Cost Report

Provides the total SMS, Data, and Voice usage for the indicated device(s) for each day during a specified time period.

Device Traffic Summary Report

Formerly named Traffic Detail Report

Provides details for all network and traffic events (billable and non-billable) for the indicated device(s) over a specified time period. All traffic events are timestamped.

Device Status Activity

Formerly named Device Activity Report

Lists all status changes, rate plan changes, and pool changes for the indicated device(s) over a specified time period in chronological order. This report does not contain any traffic information.

Trend Reports

There are three trend reports available through AerTraffic 2.1:

Device Summary

Provides a high level view of all devices categorized by current status (Provisioned, Billed or Suspended) for the last 3 months.

Overage Charges

Provides overage charges for Packet Data, SMS, and Voice for the last 3 months.

SMS/Packet

Provides total SMS (MO and MT) and Packet usage for each day over the past week.

Online Reports

Online reports are generated upon request and provide an immediate report output.

Once report generation is complete, an email containing a link to download the full report is sent to the user.

The download link provided in the email is valid for 5 days. After 5 days, the link will expire and the report must be generated again.

Scheduled Reports

Scheduled reports are generated and delivered to a set of configured email recipients based on a user-defined frequency, for example a billing report or a summary report that is generated and delivered via email once per week.

To define a scheduled report, report “templates” are created to specify the report type, report parameters and delivery frequency.

The download link provided in the email is valid for 5 days. After 5 days, the link will expire and the report must be generated again.

Scheduled reports can be delivered on a daily, weekly, or monthly frequency.

A maximum of 5 scheduled reports is allowed per account (additional scheduled reports can be requested by contacting your account manager).

Once report generation is complete, an email containing a link to download the full report is sent to each email recipient.

The download link provided in the email is valid for 5 days. After 5 days, the link will expire and the report must be retrieved from the report archives (if the report is still available).

Scheduled Report Generation

Scheduled reports are recurring and will continue to generate by the indicated frequency until the report template is deleted.

Scheduled report generation will begin at midnight GMT for the selected frequency and be delivered to the set of configured email recipients once the report is complete.

Email Recipients

Email recipients for scheduled reports are configured per report type, not by individual report.

Any change made to the recipient group of one report will affect all other scheduled reports of the same report type.

Report Archives

The amount of time that a report is available in the archives will vary:

Online Reports

Each online report will be archived for 5 days.

After 5 days, the report will expire and the report will need to be created again in order to obtain the same data.

Scheduled Reports

The 5 most recent reports for each scheduled report template will be archived.

Each daily report will be archived for 5 days.

Each weekly report will be archived for 5 weeks.

Each monthly report will be archived for 5 months.

Report Limitations

The daily scheduled report generation will start at midnight GMT. The device details captured in these reports will be correct up to the last hour.

Cost reports will be run after the End of Day rating process. Therefore, the cost details captured in these reports will be correct up to midnight GMT.

The EOD job takes variable time depending on the volume of traffic. Also, the time increases towards the end of the month therefore the report generation time will vary. The report generation will start 15 minutes after the EOD rating process.

For example: A Traffic Cost Summary Report is scheduled to run daily. On 6/10 the EOD rating process completes at 04:00 GMT. The report generating will start at 04:15 GMT and will reflect the results of the last EOD.

If the EOD rating process fails and is fixed the next day, then the cost data will not be available for cost reports. The scheduled report will still run but the email will contain a note indicating that the report may not be accurate.

It may take up to 60 minutes before new devices or recent changes are reflected in reports.

API Detailstopics

Online Reports Operations

[table id=87 /]
<!--

Online Reports

-->

Getting Started

[table id=88 /]

Create New Report

Account Traffic Cost Summary Report

URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

Schema definition: ReportDefinition

      Account Device Detail Report

      URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

      Schema definition: ReportDefinition

          Account Device Summary Report

          URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

          Schema definition: ReportDefinition

              Daily Device Traffic Usage Report

              URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

              Schema definition: ReportDefinition

                  Device Traffic Summary Report

                  URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                  Schema definition: ReportDefinition

                      Daily Traffic Detail Report

                      URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                      Schema definition: ReportDefinition

                          Device Status Activity Report

                          URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                          Schema definition: ReportDefinition

                              Get Report Status

                              URL GET https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports/{reportId}/status?preview=true&apiKey={apiKey}

                              Schema definition: ReportDefinition

                                Get List of Online Report Archives

                                URL GET http://aertrafficapi.aeris.com/v1/{accountID}/reports/archives?count=1&apiKey={apiKey}

                                Schema definition: ReportDefinition

                                  Scheduled Reports Operations

                                  [table id=92 /]

                                  Sample Requests and Responses

                                  Create New Report Template

                                  Account Traffic Cost Summary Report

                                  URL POST https://aertrafficapi.aeris.com/v1/{accountID}/scheduledReports?apiKey={API Key}

                                  Schema definition: ReportDefinition

                                      Account Device Detail Report

                                      URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                                      Schema definition: ReportDefinition

                                          Account Device Summary Report

                                          URL POST https://aertrafficapi.aeris.com/v1/{accountID}/scheduledReports?apiKey={API Key}

                                          Schema definition: ReportDefinition

                                              Daily Device Traffic Usage Report

                                              URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                                              Schema definition: ReportDefinition

                                                  Device Traffic Summary Report

                                                  URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                                                  Schema definition: ReportDefinition

                                                      Daily Traffic Detail Report

                                                      URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                                                      Schema definition: ReportDefinition

                                                          Device Status Activity Report

                                                          URL POST https://aertrafficapi.aeris.com/v1/{accountID}/onlineReports?apiKey={API Key}

                                                          Schema definition: ReportDefinition

                                                              Get List of Scheduled Templates

                                                              URL GET http://report.preprod.aeriscloud.com/v1/1/scheduledReports?apiKey={apiKey}

                                                                Get Map of Schedule Report Archives

                                                                URL GET http://report.preprod.aeriscloud.com/v1/1/scheduledReports/archives?apiKey={apiKey}

                                                                  View Scheduled Template

                                                                  URL GET https://aertrafficapi.aeris.com/v1/{account ID}/scheduledReports/{report ID}?apiKey={API Key}

                                                                  Schema definition: ReportMetadata

                                                                    Update Scheduled Template

                                                                    URL PUT https://aertrafficapi.aeris.com/v1/{account ID}/scheduledReports/{report ID}?apiKey={API Key}

                                                                    Schema definition: ReportDefinition

                                                                      Schema definition: ReportResponse

                                                                        Delete Scheduled Template

                                                                        URL DELETE https://aertrafficapi.aeris.com/v1/{account ID}/scheduledReports/{report ID}?apiKey={API Key}

                                                                          Delete Archived Report

                                                                          URL DELETE http://report.preprod.aeriscloud.com/v1/1/scheduledReports/archives/{archiveId}?apiKey={apiKey}

                                                                            View Report Recipients

                                                                            URL GET https://aertrafficapi.aeris.com/v1/{account ID}/scheduledReports/recipients/{Report Type}?apiKey={API Key}

                                                                              Update Report Recipients

                                                                              URL GET https://aertrafficapi.aeris.com/v1/{account ID}/scheduledReports/recipients?apiKey={API Key}

                                                                              Schema definition: ReportRecipients

                                                                                Schema definition: RecipientResponse

                                                                                  Trend Reports Operations

                                                                                  [table id=93 /]

                                                                                  Sample Requests and Responses

                                                                                  Traffic Summary Report

                                                                                  URL GET https://aertrafficapi.aeris.com/v1/{accountID}/systemReports/trafficSummary?durationInDays=7&apiKey={API Key}&subAccounts=false

                                                                                  Schema definition: TrafficSummaryTrendResponse

                                                                                    Overage Charges Report

                                                                                    URL GET https://aertrafficapi.aeris.com/v1/{accountID}/systemReports/costSummary?durationInMonths=2&apiKey={API Key}&subAccounts=false

                                                                                    Schema definition: CostSummaryTrendResponse

                                                                                      Device Summary Report

                                                                                      URL GET https://aertrafficapi.aeris.com/v1/{accountID}/systemReports/deviceSummary?durationInMonths=3&apiKey={API Key}&subAccounts=false

                                                                                      Schema definition: DeviceSummaryTrendResponse

                                                                                        Error codestopics

                                                                                        [table id=84 /] [table id=85 /] [table id=86 /]