How to retrieve usage csv by organization

This tutorial shows how to get the usage for your organization in CSV format. You can add filters using query parameters, to query by app ID, project HRN, or billing tag. When you add filters, the response includes elements which match the filter criteria.

There is a groupBy feature which allows you to group usage data together in the response by selecting a category, such as location services, content, SDKs, pipelines, or data. By default, there is the groupBy appId, name, and billingTag, which means that all of these properties are in the response.

Billable usage calculates at the hour level. The API supports detail at the levels of summarized, hour, day, and month, with the default level set to summarized. The principle must be part of the organization requesting usage. The maximum number of records returned in the CSV are 20,000, and the maximum time range for a query is 95 days.

API response records sort alphabetically in ascending order by subscription ID, category, and charge item (differentiates features within the same service and links to the corresponding charge).

This sample request uses org123456789 as the realmId, 2021-07-01T10:39:51 as the startDate, 2021-08-30T10:39:51 as the endDate, and 1dasda012edasfgne as the appId.

    GET https://usage.bam.api.here.com/v2/usage/realms/org123456789/csv?startDate=2021-07-01T10:39:51&endDate=2021-08-30T10:39:51&appId=j1dasda012edasfgne

Parameters

The parameters shown here are only those required for this sample request. For a complete list of parameters, see the Cost Management Usage API v2 API Reference.


realmId required	string [ 5 ... 30 ] characters. Example: org123456789 Your org ID.
startDate required	string "date-time". Example:startDate=yyyy-MM-dd'T'HH:mm:ss The start date for a search.
endDate required	string "date-time". Example:endDate=yyyy-MM-dd'T'HH:mm:ss >End date for a search.
featureId	string less than or equal to 256 characters. Example:featureId=hrn:here:service::org123456789:search-geocoding-1 Feature HRN.
appId	string less than or equal to 128 characters. Example:appId=j1dasda012edasfgne Client app ID. This is the app ID which the platform created.
channelId	string Enum: "hot" "cold" Example:channelId=cold When this parameter is available, the results filter by the ID identifying the channel used for usage reporting.
projectHrn	string less than or equal to 256 characters Example:projectHrn=hrn:here:authorization::myrealm:project/my-project-0000 The HRN which identifies the project.
billingTag	string less than or equal to 500 characters Example:billingTag=testtag Use billing tags for combining costs from your invoices.
category	string less than or equal to 128 characters Example:category=Pipelines The category is the name of the billable service you have selected, such as location services, content, SDKs, data, or pipelines.
limit	integer [ 1 .. 100 ] Default: 100 The number of records returned. The default and maximum is 100 records.
offset	integer greater than or equal to zero. Default: 0 The offset determines the current page number on the search results view.
detailLevel	string Enum: "summarized" "hour" "day" "month" Example:detailLevel=hour You can use this query parameter to select one of the levels of detail to view in your usage records. Levels of detail include: summarized, hour, day, or month. The summarized detail level shows you a summary of your usage and is the default. The usageDateTime field value isn't present if summarized is the detailLevel value.
groupBy	string less than or equal to 256 characters Example:groupBy=appId, billingTag, project, resource The groupBy parameter is a comma separated list of parameters which combine as groups. Supported values are project, billingTag, appId, featureId, and subscription ID. The default groupBy parameters are featureId and subscription ID. When you add groupBy parameters in the query, they append to featureId and subscription ID.
usageFields	Array of strings. Enum: realmId: Organization ID. featureId: Feature HRN. billingSubscriptionId: The subscription ID for your organization. billingChargeNumber: Unique charge identifier that maps to corresponding service usage costs. Combine this number with corresponding usage value to calculate billable costs. category: The product category, such as pipelines, data, content, SDKs, and location services. name: The name of the organization. valueDriver: The unit of usage value. For example, GB or Transactions. usageValue: Numerical metric to measure customer usage for a particular service. billableValue: The amount of billable usage accrued. resource: All the usage data statistics retrieved and presented to the user. Example:usageFields=realmId,featureId,category Use a set of unique or distinct usage field names to filter responses. Example:usageFields=realmId,featureId,category Use a set of unique or distinct usage field names to filter responses.

Header parameters


X-Request-ID	string User-provided token to trace a request or a group of requests sent to the service.
X-Correlation-ID required	string Auto-generated ID, which uniquely identifies the request, available in the response. When contacting the support team with an inquiry regarding a specific request, provide the value of this header. This helps when troubleshooting the issue.

Response: HTTP 200 OK

The response in CSV format lists the following columns:

Category (category): The category is the name of the billable service you have selected, such as location services, content, SDKs, data, or pipelines.
Service or Resource Name: The service, such as Navigate SDK, Network Positioning, 3D Buildings.
Billing Tag (billingTag): a user defined unique string used for combining costs.
Project ID (projectHrn): (Optional) A unique identifier to manage work and resources. This is also known as the project HRN.
Start date (startDate): The start date of the usage.
End date (endDate): The end date of the usage.
Usage amount (billableValue): How much billable usage has accrued.
Unit (valueDriver): The unit which is billable, for example GB.
Rate per Unit: The billable rate per unit.
Total Price: The calculated cost of your usage.

For partners, there is an additional column in the CSV output. The additional column is the name of the organization, orgName.