Ad Locations API
Before You Get Started 🔗
- Make sure you have read and understood the section on API Access & Authentication.
You will not be able to create or manage your Ad-Locations programmatically until the above step is completed.
Endpoints 🔗
Endpoint | Description |
---|---|
GET /v4/apps/{app_id}/ad-locations |
Gets a list of all Ad-Locations for a given app |
POST /v4/apps/{app_id}/ad-locations |
Create a new Ad-Location for a given app |
PATCH /v4/apps/{app_id}/ad-locations/{ad_location_id} |
Update an Ad-Location for a given app |
DELETE /v4/apps/{app_id}/ad-locations/{ad_location_id} |
Delete an Ad-Location for a given app |
Get all Ad-Locations 🔗
GET /v4/apps/{app_id}/ad-locations
Get a list of all ad-locations belonging to the given app_id.
Required Headers
Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8
Optional Parameters
Field | Type | Description |
---|---|---|
type_filter |
string | An optional query parameter to filter by ad-location type. Supported options are (“fixed_cpm”, “auto_cpm”, “cross_promo”, and “mock_response”). |
ad_type_filter |
string | An optional query parameter to filter by ad-type. Supported options are (“rewarded”, “interstitial”, and “banner”). |
Behavior
If no query parameters are provided, this route returns a response containing all ad-locations belonging to an app whether they are FIXED_CPM, AUTO_CPM, or CROSSPROMO and regardless of ad-type i.e. rewarded, banner, or interstitial.
- If the
type_filter
query param is provided, only ad-locations that belong to the specifiedtype
are returned. - If the
ad_type_filter
query param is provided only ad-locations that belong to the specifiedad_type
are returned.
Request Example:
GET /v4/apps/5c37c51476f3910c3cf92534/ad-locations?type_filter="fixed_cpm" HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8
200 OK Response Example:
{
"items": [
{
"uuid": "2f5fa6d4-fa06-49d1-88f6-85e2066001cf",
"name": "test_location_1",
"ad_type": "interstitial",
"type": "fixed_cpm",
"country_targeting": [
{
"country": "US",
"price": 6.0
},
{
"country": "CA",
"price": 2.55
}
]
},
...
]
}
Create a new Ad-Location 🔗
POST /v4/apps/{app_id}/ad-locations
Create a new ad-location belonging to the given app_id.
Required Headers
Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8
Request Body Fields
Field | Type | Required/Optional | Description |
---|---|---|---|
name | string | Required | The name of the ad-location. Must be between 1 and 80 characters long. Must not contain any invalid characters. It must match the following regex pattern ^[A-Za-z0-9-_$&,+\/\\\s]\*$ . Cannot have leading or trailing spaces. |
ad_type | string | Required | The ad type of the ad-location. Must be one of “interstitial”, “rewarded”, or “banner”. |
type | string | Required | The monetization type of the ad-location. At this time, only “fixed_cpm” is supported during creation. |
country_targeting | CountryTargeting[ ] |
Required | A list of country names + fixed cpm price. This field is required for “fixed_cpm” ad-locations. Array size must be between 1 and 250 elements. Cannot have duplicate values. Refer to the Country Targeting Schema table below for schema details. |
CountryTargeting Schema
Field | Type | Required/Optional | Description |
---|---|---|---|
country | string | Required | The 2-letter country code. Must be a valid ISO 3166-1 alpha-2 country code OR the value default (to target all countries) |
price | float | Required | The fixed cpm price value in USD ($) for the given country. Must be a floating point value between 0.01 and 500.00 (inclusive). Integers between 1 and 500 (inclusive) are also accepted but will be converted to floats. |
Restrictions
There are some restrictions about what ad-locations can be created. These restrictions are there to prevent monetization issues that could arise from naming conflicts.
- Uniqueness Restriction:
For a given app, there can never be multiple ad-locations with the same combination of (name + ad_type). This means that for a given name, there can be at most exactly 3 ad-locations with the same name. Example:- name: “GameOver”, ad_type: “interstitial”, …
- name: “GameOver”, ad_type: “rewarded”, …
- name: “GameOver”, ad_type: “banner”, …
- Replacement Restriction:
A newly created “fixed_cpm” ad-location cannot have the same (name + ad_type) of an existing ad-location. If that is the case, the API will return an error to prevent overwriting existing locations. The only exception is when the existing ad-location is of type “auto_cpm” at which point it will get replaced by the newly created “fixed_cpm” ad-location.
Request Example:
POST /v4/apps/5c37c51476f3910c3cf92534/ad-locations HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8
{
"name": "example",
"type": "fixed_cpm",
"ad_type": "rewarded",
"country_targeting": [
{
"country": "DE",
"price": 29.99
},
{
"country": "FR",
"price": 15.55
}
]
}
200 OK Response Example:
{
"uuid": "00af4377-c503-4559-b50f-37950bf9acd7",
"name": "example",
"ad_type": "rewarded",
"type": "fixed_cpm",
"country_targeting": [
{
"country": "DE",
"price": 29.99
},
{
"country": "FR",
"price": 15.55
}
]
}
400 Error Example:
{
"detail": [
{
"msg": "A fixed_cpm location with the same name and ad-type already exists",
"type": "existing_fixed_cpm"
}
]
}
Update an Ad-Location 🔗
PATCH /v4/apps/{app_id}/ad-locations/{ad_location_uuid}
Updates an existing ad-location belonging to the given app_id and matching the given uuid.
Required Headers
Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8
Special Considerations
- For
fixed_cpm
locations thecountry_targeting
field is fully overwritten with the new value if it is sent in the request. - Fields such as
uuid
,ad_type
, and type cannot be updated in order to preserve the integrity of the analytics data. Instead, it is recommended to delete the entire ad-location and create a new one in order to achieve the same result. - A change to the name value cannot violate the uniqueness restriction mentioned above.
Request Example:
PATCH /v4/apps/5c37c51476f3910c3cf92534/ad-locations/00af4377-c503-4559-b50f-37950bf9acd7 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8
{
"country_targeting": [
{
"country": "default",
"price": 5.00
}
]
}
Response Example:
{
"uuid": "00af4377-c503-4559-b50f-37950bf9acd7",
"name": "example",
"ad_type": "rewarded",
"type": "fixed_cpm",
"country_targeting": [
{
"country": "default",
"price": 5.00
}
]
}
Delete an Ad-Location 🔗
DELETE /v4/apps/{app_id}/ad-locations/{ad_location_uuid}
Deletes a single ad-location belonging to the given app_id and matching the given uuid.
Required Headers
Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8
Request Example:
DELETE /v4/apps/5c37c51476f3910c3cf92534/ad-locations/00af4377-c503-4559-b50f-37950bf9acd7 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8
Response Example:
204 No Content
Last modified November 27, 2023