Reporting

Contents

Reporting Endpoint

The Adastra Toll API’s reporting endpoint allows you to retrieve valuable usage statistics, performance metrics, and analytical insights. This endpoint is designed to help you monitor API usage, identify trends, and optimize your integration.

Endpoint URL

The reporting endpoint can be accessed via a GET request to the following URL:

https://api.adastrai.com/report?key=YOUR_API_KEY&secret=YOUR_SECRET_KEY

Request Parameters

The reporting endpoint requires the following parameters to be sent as query parameters in the URL:

key (Required):
- Type: string
- Description: Your API key for authentication.
- Note: API keys can be used in public client-side applications.
- Example: "YOUR_API_KEY"
secret (Required):
- Type: string
- Description: Your secret key for authentication. The secret key is required for the reporting endpoint. Without a secret key, the reporting endpoint will not function. This provides an additional layer of security since it is not intended for use in public client-side applications.
- Example: "YOUR_SECRET_KEY"
reportName (Required):
- Type: string
- Description: The name of the report to retrieve.
- Possible values:
  - "all": Returns all available reports.
  - "HourlyRequestStatistics": Hourly request statistics.
  - "DailyRequestOverview": Daily request overview.
  - "MonthlyRequestSummary": Monthly request summary.
  - "WeeklyRequestTrends": Weekly request trends.
  - "RequestCacheStatistics": Request cache statistics.
  - "SeasonalUsagePatterns": Seasonal usage patterns.
  - "RequestTrendForecast": Request trend forecast.
  - "ResponseTimeBuckets": Response time buckets.
  - "LatencyDistribution": Latency distribution.
  - "HourlyMembershipStatistics": Hourly membership statistics.
  - "ExecutionTimesByFunction": Execution times by function.
  - "ResourceUtilizationReport": Resource utilization report.
  - "ResponseCodeDistribution": Response code distribution.
  - "TopClientDomains": Top client domains.
  - "UserSegmentPerformance": User segment performance.
  - "ClientPerformanceTrends": Client performance trends.
  - "ConcurrencyAnalysis": Concurrency analysis.
  - "ErrorRateAnalysis": Error rate analysis.
  - "IPReputationAnalysis": IP reputation analysis.
  - "StepCountCategoryAnalysis": Step count category analysis.
  - "LangMapSourceMetrics": Language and map source metrics.
  - "IntegrationHealthCheck": Integration health check.
  - "VehicleTypeAnalysis": Vehicle type analysis.
  - "TollCompanyAnalysis": Toll company analysis.
  - "TollStructureBreakdown": Toll structure breakdown.
  - "HighwayTollInsights": Highway toll insights.
- Example: "all" or "DailyRequestOverview"
timeCriteria (Required):
- Type: string
- Description: The time criteria for the report. If not provided, default values are applied.
- Possible values:
  - "h": Last 1 hour.
  - "d": Last 1 day.
  - "w": Last 1 week.
  - "m": Last 1 month.
  - "y": Last 1 year.
  - "all": All time.
- Example: "d" or "m"

Response Structure

The structure of the response varies depending on the reportName parameter. When reportName is "all", the response contains all the possible reports. Other reportName parameters contain only the corresponding data. The response is in JSON format with the following common fields:

status:
- Type: string
- Description: The status of the API request. Possible values: "success", "error".
code:
- Type: integer
- Description: The HTTP status code of the response.
message:
- Type: string
- Description: A message indicating the result of the operation.
Report Data: The structure of the report data varies based on the reportName parameter. See the Detailed Report Structures section for each report’s specific data structure.
- requestDateTime:
- Type: string
- Description: The time the report request was made.
cacheDurationMinutes: * Type: integer * Description: The number of minutes the report will be cached by the server.

Detailed Report Structures

Below, you’ll find the structure of each specific report:

HourlyRequestStatistics:

    [
        {
            "HourOfDay": 8,
            "RequestCount": 2,
            "AvgResponseTime": 202
        },
         {
            "HourOfDay": 10,
            "RequestCount": 1,
            "AvgResponseTime": 494
        }
     ]

*  **`HourOfDay`**:
    * Type: `integer`
    * Description: The hour of the day (0-23).
*  **`RequestCount`**:
    * Type: `integer`
    * Description: The number of requests received during that hour.
*  **`AvgResponseTime`**:
    * Type: `integer`
    * Description: The average response time in milliseconds during that hour.

DailyRequestOverview:

    [
        {
            "RequestDate": "2024-12-20T00:00:00",
            "DailyRequestCount": 3,
            "DailyAvgResponseTime": 299,
             "DailyMinResponseTime": 51,
            "DailyMaxResponseTime": 494
        }
    ]

* **`RequestDate`**:
    * Type: `string`
    * Description: The date of the requests (in ISO 8601 format).
* **`DailyRequestCount`**:
    * Type: `integer`
    * Description: The total number of requests received during that day.
*   **`DailyAvgResponseTime`**:
    * Type: `integer`
    * Description: The average response time in milliseconds for that day.

DailyMinResponseTime:
- Type: integer
- Description: The minimum response time in milliseconds for that day.
DailyMaxResponseTime:
- Type: integer
- Description: The maximum response time in milliseconds for that day.

MonthlyRequestSummary:

    [
        {
            "RequestYear": 2024,
            "RequestMonth": 12,
            "MonthlyRequestCount": 3,
            "MonthlyAvgResponseTime": 299,
            "MonthlyMinResponseTime": 51,
            "MonthlyMaxResponseTime": 494,
            "MonthlyResponseTimeStdDev": 226.3235147600296
        }
    ]

*   **`RequestYear`**:
    *   Type: `integer`
    *   Description: The year of the requests.
*  **`RequestMonth`**:
    *   Type: `integer`
    *   Description: The month of the requests.
*   **`MonthlyRequestCount`**:
    *   Type: `integer`
    *   Description: The total number of requests received during that month.
*   **`MonthlyAvgResponseTime`**:
    *   Type: `integer`
    *   Description: The average response time in milliseconds for that month.

MonthlyMinResponseTime:
- Type: integer
- Description: The minimum response time in milliseconds for that month.
MonthlyMaxResponseTime:
- Type: integer
- Description: The maximum response time in milliseconds for that month. * MonthlyResponseTimeStdDev:
- Type: number
- Description: The standard deviation of response time in milliseconds for that month.

WeeklyRequestTrends:

   [
        {
            "RequestYear": 2024,
            "RequestWeek": 51,
            "WeeklyRequestCount": 3,
            "WeeklyAvgResponseTime": 299,
            "WeeklyMinResponseTime": 51,
            "WeeklyMaxResponseTime": 494,
            "WeeklyResponseTimeStdDev": 226.3235147600296
        }
    ]

*   **`RequestYear`**:
    *   Type: `integer`
    *   Description: The year of the requests.
*   **`RequestWeek`**:
    *   Type: `integer`
    *   Description: The week of the requests.
*   **`WeeklyRequestCount`**:
    *   Type: `integer`
    *   Description: The total number of requests received during that week.
*    **`WeeklyAvgResponseTime`**:
    *   Type: `integer`
    *   Description: The average response time in milliseconds for that week.

WeeklyMinResponseTime:
- Type: integer
- Description: The minimum response time in milliseconds for that week. * WeeklyMaxResponseTime:
- Type: integer
- Description: The maximum response time in milliseconds for that week. * WeeklyResponseTimeStdDev:
- Type: number
- Description: The standard deviation of response time in milliseconds for that week.

RequestCacheStatistics:
```
    [
        {
            "TotalRequests": 3,
            "UniqueMemberships": 1,
            "UniqueClients": 1,
            "AverageSteps": 1579,
            "CachedResponse": 0,
            "NonCachedResponse": 3,
            "CachedResponsePercentage": 0.000000000000,
            "NonCachedResponsePercentage": 100.000000000000
        }
    ]
```
- TotalRequests:
  - Type: integer
  - Description: The total number of requests received.
- UniqueMemberships: * Type: integer * Description: The number of unique memberships.
- UniqueClients:
  - Type: integer
  - Description: The number of unique clients.
- AverageSteps: * Type: integer * Description: The average number of steps in the requests.
- CachedResponse:
  - Type: integer
  - Description: The number of responses served from the cache.
- NonCachedResponse:
  - Type: integer
  - Description: The number of responses not served from the cache.
- CachedResponsePercentage:
  - Type: number
  - Description: The percentage of the cached responses.
- NonCachedResponsePercentage:
  - Type: number * Description: The percentage of the non-cached responses.

SeasonalUsagePatterns:

    [
        {
            "MonthOfYear": 12,
            "MonthName": "December",
            "RequestCount": 255,
            "AvgResponseTime": 123,
             "AvgSteps": 3963
        }
    ]

*   **`MonthOfYear`**:
    *   Type: `integer`
    *   Description: The month of the year (1-12).
*   **`MonthName`**:
    *   Type: `string`
    *   Description: The name of the month.
*   **`RequestCount`**:
    *   Type: `integer`
    *   Description: The total number of requests received during that month.
 *    **`AvgResponseTime`**:
    *   Type: `integer`
    *   Description: The average response time in milliseconds during that month.
 *  **`AvgSteps`**:
    * Type: `integer`
     * Description: The average steps during that month.

RequestTrendForecast:

    [
        {
            "RequestDate": "2024-12-20T00:00:00",
            "DailyRequestCount": 3,
            "MovingAverage7Days": 3,
            "MovingAverage30Days": 3,
            "OptimisticForecast": 3.3,
            "PessimisticForecast": 2.7
        }
    ]

*   **`RequestDate`**:
    *   Type: `string`
    *   Description: The date of the request for forecasting (in ISO 8601 format).
*  **`DailyRequestCount`**:
    *   Type: `integer`
    *   Description: The total number of requests received during that day.
*   **`MovingAverage7Days`**:
    *  Type: `number`
     *   Description: The 7-day moving average of the request count.
*   **`MovingAverage30Days`**:
    *   Type: `number`
    *   Description: The 30-day moving average of the request count.
 *   **`OptimisticForecast`**:
    *    Type: `number`
    *    Description: The optimistic forecast for requests.
 *    **`PessimisticForecast`**:
    *    Type: `number`
    *   Description: The pessimistic forecast for requests.

ResponseTimeBuckets:

    [
        {
            "ResponseTimeBucket": "100-500 ms",
            "RequestCount": 2,
            "AvgResponseTimeInBucket": 423
        },
       {
            "ResponseTimeBucket": "0-100 ms",
            "RequestCount": 1,
            "AvgResponseTimeInBucket": 51
        }
    ]

*    **`ResponseTimeBucket`**:
     *    Type: `string`
     *   Description: The range of response time.
 *    **`RequestCount`**:
     *    Type: `integer`
    *    Description: The number of requests that fall into this response time range.
*   **`AvgResponseTimeInBucket`**:
    *   Type: `integer`
    *   Description: The average response time within this range.

LatencyDistribution:

    [
        {
            "LatencyBucket": "250-500 ms",
            "RequestCount": 2,
            "Percentage": 66.670000000000
        },
        {
            "LatencyBucket": "50-100 ms",
            "RequestCount": 1,
            "Percentage": 33.330000000000
        }
    ]

LatencyBucket:
- Type: string
- Description: The range of the latency.
RequestCount:
- Type: integer
- Description: The number of requests that fall into this latency range.
Percentage:
- Type: number
- Description: The percentage of requests within this latency range.

HourlyMembershipStatistics:

    [
        {
            "HourOfDay": 8,
            "HourlyRequestCount": 2,
            "HourlyAvgResponseTime": 202,
            "HourlyMaxResponseTime": 353
        },
         {
            "HourOfDay": 10,
            "HourlyRequestCount": 1,
            "HourlyAvgResponseTime": 494,
            "HourlyMaxResponseTime": 494
        }
    ]

*   **`HourOfDay`**:
    * Type: `integer`
     * Description: The hour of the day (0-23).
*  **`HourlyRequestCount`**:
    * Type: `integer`
    * Description: The number of requests received during that hour.
*   **`HourlyAvgResponseTime`**:
    *  Type: `integer`
    *  Description: The average response time in milliseconds during that hour.
*    **`HourlyMaxResponseTime`**:
     *    Type: `integer`
     *   Description: The max response time in milliseconds during that hour.

ResourceUtilizationReport:

    [
        {
            "HourOfDay": 8,
            "TotalRequests": 2,
            "TotalSteps": 2932,
            "AvgStepsPerRequest": 1466,
            "AvgResponseTime": 202,
            "PeakResponseTime": 353
        },
        {
            "HourOfDay": 10,
            "TotalRequests": 1,
            "TotalSteps": 1806,
            "AvgStepsPerRequest": 1806,
            "AvgResponseTime": 494,
            "PeakResponseTime": 494
        }
    ]

 *   **`HourOfDay`**:
     *  Type: `integer`
     * Description: The hour of the day (0-23).
 *    **`TotalRequests`**:
      *    Type: `integer`
       *  Description: Total request count during that hour.
 *    **`TotalSteps`**:
    *    Type: `integer`
     *    Description: Total step count during that hour.
*  **`AvgStepsPerRequest`**:
    *  Type: `integer`
    *  Description: The average number of steps per request during that hour.
*    **`AvgResponseTime`**:
     *   Type: `integer`
    *   Description: The average response time during that hour.

PeakResponseTime:
- Type: integer
- Description: The maximum response time during that hour.

ResponseCodeDistribution:
```
    [
        {
            "ResponseCode": 200,
            "RequestCount": 3,
            "Percentage": 100.000000000000,
            "AvgResponseTime": 299
        }
    ]
```
- ResponseCode:
  - Type: integer
  - Description: The HTTP response code.
- RequestCount:
  - Type: integer
  - Description: The number of requests with this response code.
- Percentage:
  - Type: number
  - Description: The percentage of requests with this response code.
- AvgResponseTime: * Type: integer * Description: The average response time for this response code.

TopClientDomains:

    [
        {
            "ClientDomain": "api.adastrai.com",
            "RequestCount": 3,
            "UniqueIPs": 1,
            "AvgResponseTime": 299
        }
    ]

*   **`ClientDomain`**:
    *  Type: `string`
     *   Description: The domain of the client making the requests.
*   **`RequestCount`**:
    *   Type: `integer`
    *   Description: The number of requests from this domain.

UniqueIPs:
- Type: integer
- Description: The number of unique IPs from this domain.
AvgResponseTime:
- Type: integer
- Description: The average response time for this domain.

UserSegmentPerformance: json [ { "VehicleTypeId": 2, "Lang": "tr", "RequestCount": 3, "AvgResponseTime": 299, "MaxResponseTime": 494, "AvgSteps": 1579 } ] * VehicleTypeId:
- Type: integer
- Description: The ID of the vehicle type. * Lang: * Type: string * Description: The language code for the requests. * RequestCount: * Type: integer
- Description: The total number of requests for this user segment.
- AvgResponseTime:
  - Type: integer
  - Description: The average response time for this user segment.
- MaxResponseTime:
  - Type: integer
  - Description: The maximum response time for this user segment.
- AvgSteps:
  - Type: integer
  - Description: The average steps for this user segment.
ClientPerformanceTrends:
```
    [
        {
            "ClientDomain": "api.adastrai.com",
            "RequestDate": "2024-12-20T00:00:00",
            "RequestCount": 3,
            "AvgResponseTime": 299,
            "MinResponseTime": 51,
            "MaxResponseTime": 494
        }
    ]
```
- ClientDomain:
  - Type: string
  - Description: The domain of the client making the requests.
- RequestDate:
  - Type: string
  - Description: The date of the requests (in ISO 8601 format). * RequestCount:
  - Type: integer
  - Description: The total number of requests from this domain on this date.
- AvgResponseTime:
  - Type: integer
  - Description: The average response time from this domain on this date. * MinResponseTime:
  - Type: integer
  - Description: The minimum response time from this domain on this date. * MaxResponseTime:
  - Type: integer
  - Description: The maximum response time from this domain on this date.

ConcurrencyAnalysis:

    [
       {
            "ConcurrentRequestCount": 1,
            "Occurrences": 1,
            "AvgResponseTime": 494
        },
        {
             "ConcurrentRequestCount": 2,
            "Occurrences": 4,
            "AvgResponseTime": 202
        }
    ]

*  **`ConcurrentRequestCount`**:
    *  Type: `integer`
     *  Description: The number of concurrent requests.

Occurrences:
- Type: integer
- Description: The number of times this concurrent request count occurred.
AvgResponseTime:
- Type: integer
- Description: The average response time for this concurrency level.

StepCountCategoryAnalysis:
```
    [
       {
            "StepCountCategory": "1001-2000 Steps",
            "RequestCount": 3,
            "AvgResponseTime": 299,
            "AvgSteps": 1579
        }
    ]
```
- StepCountCategory:
  - Type: string
  - Description: The range of step counts.
- RequestCount:
  - Type: integer
  - Description: The number of requests that fall into this step count range. * AvgResponseTime:
  - Type: integer
  - Description: The average response time for the requests in this step count range.
- AvgSteps: * Type: integer *