# Ad Locations API The ad location API allows the ability to obtain and update ad location details as well as creating and deleting ad locations for a given app. ## Before you get started Complete the [API Access & Authentication](/en/monetization/reference/api-access-authentication/#api-access-url-endpoint) process. You will not be able to create or manage your ad locations programmatically until this step is completed. ## Endpoints | Version 5 Endpoints | Version 4 Endpoint | Description | | ------------------- | :----------------------------------------------------------- | :--------------------- | | [`GET /v5/apps/{app_id}/ad-locations`](/en/monetization/reference/ad-locations-api/#get-all-ad-locations) | [`GET /v4/apps/{app_id}/ad-locations`](/en/monetization/reference/ad-locations-api/#get-all-ad-locations) | Gets a list of all ad locations for a given app | | [`POST /v5/apps/{app_id}/ad-locations`](/en/monetization/reference/ad-locations-api/#create-a-new-ad-location) | [`POST /v4/apps/{app_id}/ad-locations`](/en/monetization/reference/ad-locations-api/#create-a-new-ad-location) | Create a new ad location for a given app | | [`PATCH /v5/apps/{app_id}/ad-locations/{ad_location_id}`](/en/monetization/reference/ad-locations-api/#update-an-ad-location) | [`PATCH /v4/apps/{app_id}/ad-locations/{ad_location_id}`](/en/monetization/reference/ad-locations-api/#update-an-ad-location) | Update an ad location for a given app | | [`DELETE /v5/apps/{app_id}/ad-locations/{ad_location_id}`](/en/monetization/reference/ad-locations-api/#delete-an-ad-location) | [`DELETE /v4/apps/{app_id}/ad-locations/{ad_location_id}`](/en/monetization/reference/ad-locations-api/#delete-an-ad-location) | Delete an ad location for a given app | *** ### Get all Ad Locations | Version 5 | Version 4 | | --------- | --------- | | `GET /v5/apps/{app_id}/ad-locations` | `GET /v4/apps/{app_id}/ad-locations` | Get a list of all ad locations belonging to the given **app_id**. **Required Headers** ```text 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 (“bidding”, “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 BIDDING, 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 specified `type` are returned. - If the `ad_type_filter` query param is provided only ad locations that belong to the specified `ad_type` are returned. Request Example: 200 OK Response Example: ```json { "items": [ { "uuid": "a0f68cce-f7f8-4c62-9137-dcfdf348d5b9", "name": "Bidding_INT_Next_Level", "ad_type": "interstitial", "type": "bidding" } ] } ``` *** ### Create a new Ad Location | Version 5 | Version 4 | | --------- | --------- | | `POST /v5/apps/{app_id}/ad-locations` | `POST /v4/apps/{app_id}/ad-locations` | Create a new ad location belonging to the given **app_id**. **Required Headers** ```text 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 `bidding` and `fixed_cpm` are supported during creation.| |country_targeting|schema|Optional|A list of country names + fixed cpm price. This field is specific to “fixed_cpm” ad locations only. Not supported for “bidding”. Array size must be between 1 and 250 elements. Cannot have duplicate values. Refer to the Country Targeting Schema table below for schema details. **`country_targeting` Schema** |Field|Type|Required/Optional|Description| |--|--|--|--| |country|string|Required|The 2-letter country code. Must be a valid [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2){:target="_blank"} 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. bidding Request Example: 200 OK Response Example: ```json { "uuid": "90913206-0d74-4227-b134-dcb06610595f", "name": "bidding_via_api", "ad_type": "rewarded", "type": "bidding" } ``` 400 Error Example: ```json { "detail": [ { "msg": "country_targeting can only be set for fixed_cpm ad_locations", "type": "cannot_set_country_target" } ] } ``` fixed_cpm Request Example: 200 OK Response Example: ```json { "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: ```json { "detail": [ { "msg": "A fixed_cpm location with the same name and ad-type already exists", "type": "existing_fixed_cpm" } ] } ``` *** ### Update an Ad Location | Version 5 | Version 4 | | --------- | --------- | | `PATCH /v5/apps/{app_id}/ad-locations/{ad_location_uuid}` | `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** ```text Authorization: Bearer {access-token} Content-Type: application/json; charset=UTF-8 ``` **Special Considerations** - For `fixed_cpm` locations the `country_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: Response Example: ```json { "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 | Version 5 | Version 4 | | --------- | --------- | | `DELETE /v5/apps/{app_id}/ad-locations/{ad_location_uuid}` | `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** ```text Authorization: Bearer {access-token} Content-Type: application/json; charset=UTF-8 ``` Request Example: Response Example: ``` 204 No Content ```