Learn how to use the Singular API to pull your SKAN (SKAdNetwork) data.
- For SKAdNetwork Reporting in the Singular web app, see the SKAdNetwork Reporting FAQ.
- For Singular's other reporting API endpoints (not SKAdNetwork-related), see the Reporting API Reference.
- If you are a Singular partner, you may be looking for the Get SKAN Conversion Info API Reference (SKadNetwork API for Singular Partners).
Create Async SKAdNetwork Report Endpoint
POST | https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report |
Usage
This endpoint generates an asynchronous report query for Singular SKAdNetwork data and returns a Report ID. The next step is to query the Get Report Status endpoint to see when the report is done and to get a download URL.
Sample Query (Python)
import requests
url = "https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report"
params = {"api_key": API_KEY}
data = {
"skadnetwork_date_type": "skan_postback_date",
"start_date": "2021-01-01",
"end_date": "2021-01-01",
"dimensions": "app,source,skan_network_id,skan_campaign_id,skan_app_id,skan_publisher_id,skan_conversion_value,skan_redownloads,skan_validated,country_field",
"metrics": "skan_installs",
"filters": '[{"dimension": "skan_validated", "operator": "in", "values": ["false"]},{"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]',
"time_breakdown": "all",
}
response = requests.post(url=url, params=params, data=data)
Query Parameters
Parameter | Format | Description | Example |
Basic Parameters | |||
api_key | String | API key provided in the Singular console | |
start_date | Date | '2020-12-01' | |
end_date | Date | '2020-01-10' | |
time_breakdown | String | How to break down the results: - "day" - "week" - "month" - "all" (display aggregated data over the entire date range) |
'all' |
skadnetwork_date_type | String | Choose which type of date you want the report to be based on: - "skan_postback_date" (default) - the date the SKAN postback was sent by the device. - "estimated_install_date" - the install date as calculated by Singular (see How does Singular calculate the install date?). |
'estimated_install_date' |
Field Selection Parameters | |||
dimensions | String | A comma-separated list of dimensions. See the table below for the dimensions available for SKAdNetwork reports are. | |
metrics | String | A comma-separated list of metrics. The only metric available for SKAdNetwork reports at this point is skan_installs. | 'skan_installs' |
Filtering Parameters | |||
app | String | A comma-separated list of app names to filter the query results by. To retrieve a list of app names, use the Filters endpoint. | 'my_app1, my app2' |
source | String | A comma-separated list of ad networks (and other sources) to filter by. To retrieve a list of ad network names, use the Filters endpoint. | 'facebook,adwords' |
filters | An array of JSON objects where each object contains a dimension, an operator, and a value to filter by. Use this parameter to apply more advanced filtering. Note that if you specify more than one filter they will be applied with an AND relation. Available filters for SKAdNetwork reports (see details in the Available Dimensions table below) "country_field" "skan_redownloads" "skan_validated" |
'[{"dimension": "skan_validated", "operator": "in", "values": ["false"]}, {"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]' |
|
Formatting Parameters | |||
format | String | The format in which the query results will be delivered. Options: "json" (default) or "csv". | 'csv' |
country_code_format | String | Either "iso3" (default) or "iso" | 'iso' |
Available Dimensions
Dimension | Description |
skan_app_id | The value of the 'app-id' parameter in Apple's SKAdNetwork postback. |
skan_network_id | The value of the 'ad-network-id' parameter in Apple's SKAdNetwork postback. |
skan_campaign_id | The value of the 'campaign-id' parameter in Apple's SKAdNetwork postback. |
skan_publisher_id | The value of the 'source-app-id' parameter in Apple's SKAdNetwork postback. |
app | The app name in Singular (derived from skan_app_id). |
source | The ad network name as it is listed in Singular (derived from skan_network_id). |
country_field | Derived from the IP that's included in the SKAdNetwork postback. |
skan_conversion_value | |
skan_redownloads | Apple's SKAdNetwork postbacks include a "redownload" field. According to Apple, this is set to true if the app has already been downloaded and installed by the same user (same Apple ID). Singular marks every SKAdNetwork install accordingly as either a "download" or a "redownload". |
skan_validated | As a part of Singular's SKAdNetwork solution, Singular not only receives and parses SKAdNetwork postbacks from ad networks, but also checks with Apple to confirm that each postback represents an actual install. Validation ensures that installs are not fraudulent. |
SKAN-Specific Error Codes
Singular uses standard HTTP response codes to indicate the success or failure of an API request. In general, 200 codes correspond to success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx codes are for other issues.
See also: List of general error codes returned by the Reporting API
Error message | Solution |
There is no SKAdNetwork data configured. | |
'is_skadnetwork_report' param expected to receive value 'true', got 'xxx' instead | Make sure your parameter values match the permitted values listed in the table above. |
'skadnetwork_date_type" param expected to receive one of the following values (...), got '...' instead. | |
The dimensions ['...'] can not be requested in an SKAdNetwork report. | |
The metrics ['...'] can not be requested in an SKAdNetwork report. | |
The '...' filter expected to receive one of the following values ['false','true', got '...' instead. |