From 9b37361c1d71476104b3328dd5fedf8e954c3ebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 21 Nov 2024 11:09:21 +0100 Subject: [PATCH] docs: Address PR feedback --- src/content/docs/en/api/reports-service.mdoc | 415 +++---------------- 1 file changed, 62 insertions(+), 353 deletions(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 2706c642a..d1bcb9cec 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -21,7 +21,7 @@ If your user is associated with multiple accounts, you can choose which account 1. Pass the account ID as an `X-Account-ID` header in each request. ```sh -curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ +curl --location "https://automate.adjust.com/reports-service/events?events__contains=purchase&tokens_mapping=true" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` @@ -30,16 +30,16 @@ curl --location "https://automate.adjust.com/reports-service/filters_data?requir The Reports Service API returns the following response codes for each endpoint: -| Response | Message | Notes | -| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `200` | `Success` | Returns report information | -| `204` | `No content` | Returned if the response object is empty | -| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | -| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | -| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | -| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | -| `503` | `Service unavailable` | Returned if the server can't be reached | -| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | +| Response | Message | Notes | +| -------- | --------------------- | --------------------------------------------------------------------------- | +| `200` | `Success` | Returns report information | +| `204` | `No content` | Returned if the response object is empty | +| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | +| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | +| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | +| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | +| `503` | `Service unavailable` | Returned if the server can't be reached | +| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | ## Fetch required data {% #fetch-required-data %} @@ -49,172 +49,6 @@ You must provide filters when querying the Reports Service API. Follow these ins When querying the Reports Service API, you need to filter your reporting data. The Reports Service API supports different filters such as metrics and dimensions. A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary) and a full list of dimensions is available in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). -You can fetch filters programmatically using the `filters_data` endpoint. This endpoint returns a full representation of all matching filters. - -```http -GET https://automate.adjust.com/reports-service/filters_data -``` - -#### Parameters - -You MUST pass the following as a **query parameter**: - -{% deflist %} -`required_filters`: `String` - -: A comma-separated list of filters. -{% /deflist %} - -The following filters are available: - -| Filter | Description | -| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `apps` | Returns a list of your apps. | -| `apps_network` | Returns a list of your apps and their associated store IDs. | -| `overview_metrics` | Returns a list of overview metrics. | -| `skad_metrics` | Returns a list of metrics relating to SKAdNetwork. | -| `cohort_maturity` | Returns a list of metrics relating to the maturity of a cohort. Example: mature, immature. | -| `cohort_metrics` | Returns a list of metrics relating to your cohorts. | -| `event_metrics` | Returns a list of metrics relating to your events. All metrics are duplicated per event. | -| `cost_metrics` | Returns a list of metrics relating to cost. | -| `etl_metrics` | Returns a list of metrics relating to ETL (extract, transform, load) between Adjust and another system. | -| `dimensions` | Returns a list of dimensions. | -| `countries` | Returns a list of countries. | -| `currencies` | Returns a list of currencies. | -| `os_names` | Returns a list of operating system names. | -| `networks` | Returns a list of networks. | -| `partners` | Returns a list of partners. | -| `ad_revenue_sources` | Returns a list of ad revenue sources. | -| `iap_revenue_mode` | Returns a list of ad revenue modes. | -| `attribution_type` | Returns a list of attribution types. Examples: all, click, impression. | -| `attribution_source` | Returns a list of attribution sources. | -| `attribution_status` | Returns a list of attribution statuses. | -| `ad_spend_mode` | Returns a list of cost modes. Examples: attribution, network, mixed. | -| `ad_spend_mode` | Returns a list of ad spend modes. Examples: attribution, network, mixed. | -| `utc_offset` | The offset (in hours) from UTC. Defaults to 0 (UTC). | -| `attributes` | Returns a list of attributes. | -| `index` | Returns a list of key metrics that relate to all apps. | -| `period_over_period` | Returns a list of time periods used for data comparison. | -| `cohort_metric_names` | Returns a list of readable names for cohort metrics. | -| `full_cohort_periods` | Returns a list of time periods related to cohorts. | -| `store_type` | Returns a list of app stores. | -| `skad_time_adjustment` | Returns a list of valid SKAdNetwork activity windows. | - -You MAY pass the following as **query parameters**: - -{% deflist %} -`section`: `String` - -: The section you want to filter items by. - -`[required_filters]__contains`: `String` - -: A search term to filter your selected required filters by. -{% /deflist %} - -The following sections are available: - -| Section | Description | -| ----------------------------------------------------- | ----------------------------------------------------- | -| `conversion` | Metrics relating to click and impression conversions. | -| `fraud` | Metrics relating to fraud prevention. | -| `cost` | Metrics relating to cost. | -| `revenue` | Metrics relating to app revenue. | -| `retention` | Metrics relating to cohort-based user retention. | -| `events` | Metrics relating to events. | -| `conversion_events` | Metrics relating to SKAdNetwork conversion events. | -| `installs` | Metrics relating to app installs and reinstalls. | -| `conversion_values` | Metrics relating to SKAdNetwork conversion values. | - -#### Response format - -```json -{ - "required_filters_1": [ - { - "id": "string", - "name": "string", - "short_name": "string", - "section": "string", - "formatting": "string", - "description": "string", - "increase_is_negative": false - } - ] -} -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```json -{ - "cost_metrics": [ - { - "id": "network_ad_spend_skan", - "name": "Ad spend (SKAN)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "The amount spent on ads for SKAN campaigns as reported by the network API", - "increase_is_negative": false - }, - { - "id": "network_cost", - "name": "Ad spend (network)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "Ad spend data retrieved via the network API", - "increase_is_negative": true - }, - { - "id": "network_cost_diff", - "name": "Ad spend diff (network)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "Difference between the attribution and network data sources", - "increase_is_negative": true - } - ], - "overview_metrics": [ - { - "id": "skad_ecpi", - "name": "eCPI (SKAN)", - "short_name": "", - "section": "Cost", - "formatting": "decimal", - "description": "Effective cost per install, calculated by dividing the amount spent on ads for SKAN campaigns by installs", - "increase_is_negative": false - }, - { - "id": "ecpi_all", - "name": "eCPI (all installs)", - "short_name": "eCPI (all)", - "section": "Cost", - "formatting": "money", - "description": "Effective cost per install", - "increase_is_negative": true - }, - { - "id": "ecpi", - "name": "eCPI (paid installs)", - "short_name": "eCPI (paid)", - "section": "Cost", - "formatting": "money", - "description": "Effective cost per paid install", - "increase_is_negative": true - } - ] -} -``` - ### Retrieve event slugs {% #retrieve-event-slugs %} If you want to query your reporting data using your Adjust events, you need to retrieve the slugs for your events by calling the `events` endpoint. This endpoint enables you to search for events using their readable names and returns useful information about each one. @@ -314,11 +148,11 @@ For each reporting endpoint, you MUST pass the following **query parameters**: {% deflist %} `dimensions`: `String` -: A comma-separated list of dimensions to group results by. You can fetch dimensions from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). +: A comma-separated list of dimensions to group results by. You can find a full list in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). `metrics`: `String` -: A comma-separated list of metrics to report on. You can fetch metrics from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). +: A comma-separated list of metrics to report on. You can find a full list in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). `date_period`: `String` @@ -334,7 +168,7 @@ You MAY pass the following as **query parameters**: {% deflist %} `cohort_maturity`: `String` -: Whether to include all cohort metric values (`immature`) or only mature cohorts `mature`. If you pass `mature`, any values for immature cohorts are displayed as zeros. +: Whether to include all cohort metric values (`immature`) or only mature cohorts `mature`. If you pass `mature`, any values for immature cohorts are displayed as zeros. See [How cohorts work on the Adjust Help Center](https://help.adjust.com/en/article/how-cohorts-work#cohort-maturity). `utc_offset`: `String` @@ -342,7 +176,7 @@ You MAY pass the following as **query parameters**: `attribution_type`: `String` -: The type of engagement the attribution awards. +: The type of engagement the attribution awards. See the [attribution type documentation on the Adjust Help Center](https://help.adjust.com/en/article/set-up-your-view-in-datascape#attribution-type). - `click` (default) - `impression` @@ -371,6 +205,7 @@ You MAY pass the following as **query parameters**: - `GROSS_70` - `GROSS_65` - `GROSS_60` +- `GROSS_50` `ad_revenue_sources`: `String` @@ -444,31 +279,71 @@ You MAY pass the following as **query parameters**: : A substring to filter a given dimension by suffix. Case insensitive. -`[metric]__lt`: `String` +`[metric]__lt`: `Number` : "Less than" filter. Returns only values lower than the specified value for the specified metric. -`[metric]__lte`: `String` +`[metric]__lte`: `Number` : "Less than or equal to" filter. Returns only values lower than or equal to the specified value for the specified metric. -`[metric]__gt`: `String` +`[metric]__gt`: `Number` : "Greater than" filter. Returns only values higher than the specified value for the specified metric. -`[metric]__gte`: `String` +`[metric]__gte`: `Number` : "Greater than or equal to" filter. Returns only values greater than or equal to the specified value for the specified metric. -`[metric]__eq`: `String` +`[metric]__eq`: `Number` : "Equal to" filter. Returns only values equal to the specified value for the specified metric. -`[metric]__ne`: `String` +`[metric]__ne`: `Number` : "Not equal to" filter. Returns only values not equal to the specified value for the specified metric. {% /deflist %} +### Fetch a CSV report {% #fetch-csv-report %} + +The `csv_report` endpoint returns data in a comma-separated values format, perfect for importing into spreadsheet software or other tools that require a flat file structure. This format is ideal for users who prefer to work with data in Excel or similar applications for further manipulation and reporting. + +```http +GET https://automate.adjust.com/reports-service/csv_report +``` + +#### Parameters + +In addition to the [parameters for each endpoint](#report-parameters), you MAY pass the following **query parameter** when calling the `csv_report` endpoint: + +{% deflist %} +`readable_names`: `Boolean` + +: Whether to return columns with their human-readable names. Defaults to `false`. +{% /deflist %} + +Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [events endpoint](#retrieve-event-slugs) to retrieve event slugs. + +#### Response format + +```text +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +String,String,String,String,String,Number,Number +``` + +#### Example + +```sh +curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" \ + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" +``` + +```csv +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 +``` + ### Fetch a JSON report {% #fetch-json-report %} The `report` endpoint enables you to combine data from many services in a single report. Request installs, revenue, ad spend, and SKAdNetwork data divided by day, app, and ad network. @@ -540,169 +415,3 @@ curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mod "pagination": null } ``` - -### Fetch a pivot report {% #fetch-pivot-report %} - -The `pivot_report` endpoint delivers data in a structured, pivot-table format. It allows you to group and aggregate data across multiple dimensions, making it easier to summarize and compare key metrics. This is useful when you want to analyze patterns or trends without having to manually manipulate the raw data. - -```http -GET https://automate.adjust.com/reports-service/pivot_report -``` - -#### Parameters - -In addition to the [mandatory parameters for each endpoint](#report-parameters), you MUST pass the following **query parameter** when calling the `pivot_report` endpoint: - -{% deflist %} -`index`: `String` - -: A comma-separated list of dimensions used to index the report. -{% /deflist %} - -#### Response format - -```json -{ - "rows": [], - "totals": {}, - "data_warnings": [], - "debug": { - "service_urls": [ - { - "method": "string", - "url": "string", - "params": {}, - "data": {}, - "status_code": 0, - "duration": 0 - } - ], - "cached_at": "2019-08-24T14:15:22Z" - }, - "currencies": [], - "immature_cohorts": {}, - "totals_per_dimension": {} -} -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/pivot_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi&index=app" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```json -{ - "rows": [ - { - "Test App": { - "rows": [ - { - "attr_dependency": { - "app_network": ["google_play:com.test.app"] - }, - "campaign_id_network": "123", - "campaign_network": "Campaign Name", - "campaign": "Campaign Name (123)", - "partner_name": "MyPartner", - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - ] - } - } - ], - "totals": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - }, - "totals_per_dimension": { - "campaign_id_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "app": { - "adjust Demo App": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "partner_name": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - } - } -} -``` - -### Fetch a CSV report {% #fetch-csv-report %} - -The `csv_report` endpoint returns data in a comma-separated values format, perfect for importing into spreadsheet software or other tools that require a flat file structure. This format is ideal for users who prefer to work with data in Excel or similar applications for further manipulation and reporting. - -```http -GET https://automate.adjust.com/reports-service/csv_report -``` - -#### Parameters - -In addition to the [parameters for each endpoint](#report-parameters), you MAY pass the following **query parameter** when calling the `csv_report` endpoint: - -{% deflist %} -`readable_names`: `Boolean` - -: Whether to return columns with their human-readable names. Defaults to `false`. -{% /deflist %} - -Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [events endpoint](#retrieve-event-slugs) to retrieve event slugs. - -#### Response format - -```text -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -String,String,String,String,String,Number,Number -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```csv -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 -```