Important
The following guide presupposes knowledge of APIs and how they work. If you don't know how to make API calls, be sure to work with software engineers or other personnel who are able to do so on your behalf.
You can use the Publisher Summary API to pull performance data. Learn how to generate performance data reports.
Step 1: Authenticate using an access token.
You need an access token to start using the Publisher Summary API. To get an access token, you must prepare your email address and password for signing in to Moloco Publisher Portal as well as your Platform ID.
Prepare your email address and password
After signing up, you should have received an email from Moloco to create a password for your account. If you haven't received this email in the inbox of the email address you used to sign up for an account with us, reach out to your Moloco representative for assistance. Follow the instructions in the email to create your password.
Find and copy your Platform ID in Moloco Publisher Portal
To find your Platform ID, sign in to Moloco Publisher Portal and click Publisher setting from the left sidebar. Find and copy the Platform ID for your account.
Make an API request to generate an access token
Once you have your email address, password, and Platform ID, you must make an API request to generate an access token. In the following sample request, you must enter your email address for email, password for password, and Platform ID for workplace_id.
curl --request POST \
--url https://managefnt.adsmoloco.com/api/adcloud/publisher/v1/auth/tokens \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data @- <<EOF
{
"email": "<your-email-address-here>",
"password": "<your-password-here>",
"workplace_id": "<your-platform-id-here>"
}
EOF
The response returned includes the token ID you need to include in the header when using the Publisher Summary API endpoint. The token is valid for up to 60 minutes and after it has expired you must make a new API request to generate a new access token.
{
"token": "your-token-here"
}
Before the token expires, you can refresh by making the following API request with the existing token included, which returns a new token in the response. As you can see in the following sample request, you must include your access token as a bearer token when making API requests that require authorization.
curl --request PUT \
--url https://managefnt.adsmoloco.com/api/adcloud/publisher/v1/auth/tokens \
--header 'Authorization: Bearer <your-token-here>' \
--header 'accept: application/json'
Step 2: Make an API request for the Publisher Summary API endpoint.
You must use the following API endpoint.
POST https://managefnt.adsmoloco.com/api/adcloud/publisher/v1/sdk/summary
Required properties
The following properties must be included in the request body.
| Property | Type | Description |
| publisher_id | string | This is the Publisher ID which you can copy from Moloco Publisher Portal by navigating to Publisher settings > Publisher info. |
| date_range | object |
This is the date range to pull data from. You can specify a date range of up to 31 days. You must specify both start and end dates in the following format. "date_range": {
|
| dimensions | array | This is the dimension(s) you would like to group data by. See the available dimensions for more information. |
| metrics | array | This is the metric(s) you would like to include in the data summary, grouped by the dimension(s) you have specified. See the available metrics for more information. |
| dimension_filters | array of objects |
This is the filter(s) you would like to apply to the data to retrieve only a subset of data. You must use the following format. "dimension_filters": [ |
| order_by | array of objects |
This determines how the data retrieved is organized in the response. Data can be organized by any of the available dimensions and metrics. You must use the following format. "order_by": [ |
Available metrics
You must include one or more of the following metrics in the request body.
| Metric | Type | Description |
| REVENUE | number | This is the estimated revenue amount in USD. |
| IMPRESSIONS | number | This is the total number of impressions, which tells you how many times creative(s) displayed in your inventories have been viewed. |
| REQUESTS | number | This is the total number of bid requests made to Moloco from the mediation platform or bidding layer. |
| CLICKS | number | This is the total number of ad clicks from users. |
| ECPM | string | This is the eCPM, calculated as (revenue x 1000) / impressions. |
| IMP_FILL_RATE | string | This is the ad fill rate, calculated as impressions / requests. |
Available dimensions
You must include one or more of the following dimensions in the request body.
| Dimension | Type | Description |
| UTC_DATE | string |
This is date in the following format. YYYY-MM-DD HH:mm:SS +0000 UTC e.g.,) |
| PUBLISHER_APP_ID | string |
This is the Moloco-generated App Key you can find on Moloco Publisher Portal by navigating to Apps > app > App Detail. e.g.,) |
| PUBLISHER_APP_TITLE | string |
This is the title you have specified for an app. e.g.,) |
| AD_UNIT_TITLE | string |
This is the title you have specified for an ad unit. e.g.,) |
| AD_UNIT_ID | string |
This is the Moloco-generated Ad Unit ID you can find on Moloco Publisher Portal by navigating to Ad Units > ad unit > Ad Unit Detail. e.g.,) |
| DEVICE_OS | enum |
This is the OS type of an app. Acceptable values are |
| GEO_COUNTRY | string |
This is the ISO 3166 Alpha-3 code obtained from a user's IP address. e.g.,) |
| PUBLISHER_APP_STORE_ID | string |
This is the Store ID (for iOS) or the Package Name (for Android) for an app. e.g.,) Store ID: Package Name: |
| PUBLISHER_APP_PACKAGE_NAME | string |
This is the Package Name for an Android app. e.g.,) |
| ADUNIT_AUCTION_METHOD | enum | This is the type of auction method for an ad unit. Acceptable values are IN_APP_BIDDING and WATERFALL. |
Request body
The request body must be formatted as follows.
{
"publisher_id": "<MOLOCO-PUBLISHER-ID>",
"date_range": {
"start": "YYYY-MM-DD",
"end": "YYYY-MM-DD"
},
"dimensions": ["<DIMENSION_NAME>"],
3
"metrics": ["<METRIC_NAME>"],
"dimension_filters": [
{
"dimension": "<DIMENSION_NAME>",
"values": ["string"]
}
],
"order_by": [
{
"dimension" | "metric": "<DIMENSION_NAME> | <METRIC_NAME>",
"is_descending": true|false
}
]
}
The following sample request returns in the response, the total revenue amount by date from June 10 2023 to June 11 2023.
curl --request POST \
--url https://managefnt.adsmoloco.com/api/adcloud/publisher/v1/sdk/summary \
4
--header 'content-type: application/json' \
--header 'Authorization: Bearer <your-token-here>' \
--data @- <<EOF
{
"publisher_id": "<your-publisher-id>",
"date_range": {
"start": "2023-06-10",
"end": "2023-06-11"
},
"dimensions": ["UTC_DATE"],
"metrics": ["REVENUE"]
}
EOF
Filter data
You can apply filter(s) to the data to retrieve only a subset of data. You can specify any of the available dimensions as filters as in the following example.
{
"publisher_id": "<your-publisher-id>",
"date_range": {
"start": "2023-06-10",
"end": "2023-06-15"
6
},
"dimensions": ["UTC_DATE", "AD_UNIT_ID"],
"metrics": ["REVENUE", "IMPRESSIONS"],
"dimension_filters":[
{
"dimension": "PUBLISHER_APP_ID",
"values": [ "<moloco-app-id>"]
},{
"dimension": "GEO_COUNTRY",
"values": ["USA", "CAN"]
}]
}
This sample request returns in the response the total revenue amount and total number of impressions from June 10th 2023 to June 15th 2023 from Canada and the US for an app with the App Key <moloco-app-id>, grouped by date and Ad Unit ID.
Group and arrange data by one or more dimensions and/or metrics
You can group data by one or more of the available dimensions and/or metrics. The following sample request returns in the response the ad fill rate and total number of clicks by date and App Key, with date displayed from least to most recent and fill rate displayed from greatest to least.
{
"publisher_id": "<your-publisher-id>",
"date_range": {
"start": "2023-06-10",
"end": "2023-06-11"
},
"dimensions": ["UTC_DATE", "PUBLISHER_APP_ID"],
"metrics": ["FILL_RATE", "CLICKS"],
"order_by": [{
"dimension": "TIME_BUCKET",
"is_descending": false
}, {
"metric": "FILL_RATE",
"is_descending": true
}]
}
Response body
The response returned from the API request is formatted as follows. Only the dimensions and/or metrics specified in the API request are returned in the response.
{
"rows": [
{
"utc_time_bucket": "YYYY-MM-DD",
"app": {
"app_id": "<moloco-app-id-in-inventory-sheet>",
"app_title": "<pretty-app-name>"
},
"ad_unit": {
"ad_unit_id": "<moloco-ad-unit-id-in-inventory-sheet>",
"ad_unit_title": "<pretty-ad-unit-name>",
"inventory_type": "BANNER" | "INTERSTITIAL" | "REWARD_VIDEO",
"bidfloor": string
},
"device": {
"os": "IOS" | "ANDROID"
},
"geo": {
"country": "<ISO 3166-1 alpha-3 country code>"
},
"metric": {
"revenue": float64,
"impressions": int64,
"requests": int64,
"clicks": int64,
"ecpm": float64,
"fill_rate": float64
}
}
]
}
Metrics
| Metric | Type | Description |
| REVENUE | number |
This is the estimated revenue amount in USD. e.g.,)130.15
|
| IMPRESSIONS | number |
This is the total number of impressions, which tells you how many times creative(s) displayed in your inventories have been viewed. e.g.,) |
| REQUESTS | number |
This is the total number of bid requests made to Moloco from the mediation platform or bidding layer. e.g.,) |
| CLICKS | number |
This is the total number of ad clicks from users. e.g.,) |
| ECPM | string |
This is the eCPM, calculated as (revenue x 1000) / impressions. e.g.,) |
| IMP_FILL_RATE | string |
This is the ad fill rate, calculated as impressions / requests. e.g.,) |
Dimensions
| Dimension | Type | Description |
| UTC_DATE | string |
This is date in the following format. YYYY-MM-DD HH:mm:SS +0000 UTC e.g.,) |
| PUBLISHER_APP_ID | string |
This is the Moloco-generated App Key you can find on Moloco Publisher Portal by navigating to Apps > app > App Detail. e.g.,) |
| PUBLISHER_APP_TITLE | string |
This is the title you have specified for an app. e.g.,) |
| AD_UNIT_TITLE | string |
This is the title you have specified for an ad unit. e.g.,) |
| AD_UNIT_ID | string |
This is the Moloco-generated Ad Unit ID you can find on Moloco Publisher Portal by navigating to Ad Units > ad unit > Ad Unit Detail. e.g.,) |
| DEVICE_OS | enum |
This is the OS type of an app. Valid values are |
| GEO_COUNTRY | string |
This is the ISO 3166 Alpha-3 code obtained from a user's IP address. e.g.,) |
| PUBLISHER_APP_STORE_ID | string |
This is the Store ID (for iOS) or the Package Name (for Android) for an app. e.g.,) Store ID: Package Name: |
| PUBLISHER_APP_PACKAGE_NAME | string |
This is the Package Name for an Android app. e.g.,) |
| ADUNIT_AUCTION_METHOD | enum | This is the type of auction method for an ad unit. Valid values are IN_APP_BIDDING and WATERFALL. |
The following is a sample request for revenue amount by date and OS type from June 10 2023.
curl --request POST \
--url https://managefnt.adsmoloco.com/api/adcloud/publisher/v1/sdk/summary \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <your-token-here>' \
--data @- <<EOF
{
"publisher_id": "<your-publisher-id>",
"date_range": {
"start": "2023-06-10",
"end": "2023-06-10"
},
"dimensions": ["UTC_DATE", "DEVICE_OS"],
"metrics": ["REVENUE"]
}
EOF
The response returned includes only the information that was requested.
{
"rows": [
{
"utc_time_bucket": "2023-06-10 00:00:00 +0000 UTC",
"device": {
"os": "IOS"
},
"metric": {
"revenue": 100.01
}
}, {
"utc_time_bucket": "2023-06-10 00:00:00 +0000 UTC",
"device": {
"os": "ANDROID"
},
"metric": {
"revenue": 99.99
}
}
]
}
Timezones and availability
We use UTC timezone for pulling and displaying datasets. While most data is available in real time, it may take a couple of hours for some of the data to be made available. As a result, you can expect a full day's worth of data to be made available up to 6 hours past midnight UTC of the day data was recorded.
Service level agreement
We will release fixes to issues raised by publishers within three business days from the date the issue was initially reported.