Geography Targeting (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 29, 2017
Version 7Show Document
  • View in full screen mode

Description

Use the Geography Targeting API to deliver the line items on specific set of Countries, Cities, Regions/States, and DMAs.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ) provided in the POST call.  You should retrieve the valid target details using Common Geo API and provide id's for respective targeting.
  2. Ensure that the same targetValues are not being included / excluded at the same time for same line item.

This API must be called after creating/updating Line Item successfully since it require lineitemId during targeting.

For more information about Line Item Targeting Services, refer to Line Item Targeting Services (UAS)

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/geosPOSTAdd/Remove/Update geo targeting for the Line ItemConfigure Geographies for a Line Item
/lineitems/{lineItemid}/targets/geosGETRetrieve the details of a specific Ad Unit for requested Ad Unit ID.Retrieve Targeted Geographies for a Line Item

 

Configure Geographies for a Line Item

 

Overview

This API enables you to add, update or remove geographies for a Line Item.

 

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

You can retrieve the geo information at various level such as Country, Region/State, City, DMA, etc. using targetValue.

The following are valid Target Levels for Geography Targeting:

                                 
Target LevelTargetDescriptionSample URL
1CountryCountry Level TargetingTo retrieve all the countries supported for Targeting: http://$URI_PREFIX/api/common/geo?filters=geoLevel eq 1&showAll=true 
2Region/StateRegion/State Level Targeting

To retrieve all the region/state for a specific country.

Example: For the United States - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,countryCode&filters=geoLevel EQ 2&filters=countryCode EQ US

3CityCity Level Targeting

To retrieve all the City for a particular RegionState

Example: For the state of New York - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,regionCode,countryCode&filters=geoLevelEQ 3&filters=countryCode EQ US&filters=regionCode EQ NY

You will need to use pagination parameters to retrieve more cities if available.

4DMADMA Level Targeting

We currently only support DMA for country United States Of America.

EXAMPLE: For country US

http://$URI_PREFIX/api/common/geo?filters=geoLevel EQ 4&filters=countryCode EQ US

You need to use pagination parameters to retrieve more DMA records if available.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

TargetValue will contain reference value.

                            
Target TypeTarget Value Data TypeReference/Actual Value
CountryNumeric

Reference Value.  id attribute from the response returned byhttp://$URI_PREFIX/api/common/geo API

Region/StateNumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
CityNumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
DMANumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
excludeBooleanYes

Default will be false.

Valid values can be true or false

The exclude parameter defines the behavior of targeting. By default specified targetLevel and targetValue will be included as exclude will be false.

You can either include or exclude the entities during targeting for given line time for entities at same level. E.g. You can include Country as United State but none of other countries you can exclude which will create a conflict during LineItem targeting.

However you can exclude states, cities from United state if want.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/geos/ 

Sample Request JSON

{
    "targets": [
        {
            "targetValue": 107,
            "targetLevel": 1,
            "exclude": true
        },
        {
            "targetValue": 162908,
            "targetLevel": 2,
            "exclude": false
        },
        {
            "targetValue": 5818,
            "targetLevel": 3,
            "exclude": false
        },
        {
            "targetValue": 162688,
            "targetLevel": 4,
            "exclude": true
        },
        {
            "targetValue": "P10036",
            "targetLevel": 5,
            "exclude": false
        }
    ]
}

Sample Request JSON: To Remove all Geography Targeting for a Line Item

{
    "targets": []
}

Response

Sample Response JSON    

{
    "entity":
    {
        "id": {targetid associated with lineitem},
    },
    "targets":
    [
        {
            "targetValue": 107,
            "exclude": true,
            "targetLevel": 1,
            "countryCode": "IN",
            "cityName": "India",
            "dmaCode": 0
        },
        {
            "targetValue": 162908,
            "exclude": false,
            "targetLevel": 2,
            "countryCode": "US",
            "cityName": "Virgin Islands",
            "dmaCode": 0
        },
        {
            "targetValue": 5818,
            "exclude": false,
            "targetLevel": 3,
            "countryCode": "IN",
            "cityName": "Pune",
            "dmaCode": 0
        },
        {
            "targetValue": 162688,
            "exclude": true,
            "targetLevel": 4,
            "countryCode": "US",
            "cityName": "New York",
            "dmaCode": 501
        }
    ]
}

 

Retrieve Targeted Geographies for a Line Item

 

Overview

This API enables you to retrieve target geographies for a Line Item.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

You can retrieve the geo information at various level such as Country, Region/State, City, DMA, etc. using targetValue.

The following are valid Target Levels for Geography Targeting:

                                 
Target LevelTargetDescriptionSample URL
1CountryCountry Level TargetingTo retrieve all the countries supported for Targeting: http://$URI_PREFIX/api/common/geo?filters=geoLevel eq 1&showAll=true 
2Region/StateRegion/State Level Targeting

To retrieve all the region/state for a specific country.

Example: For the United States - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,countryCode&filters=geoLevel EQ 2&filters=countryCode EQ US

3CityCity Level Targeting

To retrieve all the City for a particular RegionState

Example: For the state of New York - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,regionCode,countryCode&filters=geoLevelEQ 3&filters=countryCode EQ US&filters=regionCode EQ NY

You will need to use pagination parameters to retrieve more cities if available.

4DMADMA Level Targeting

We currently only support DMA for country United States Of America.

EXAMPLE: For country US

http://$URI_PREFIX/api/common/geo?filters=geoLevel EQ 4&filters=countryCode EQ US

You need to use pagination parameters to retrieve more DMA records if available.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

TargetValue will contain reference value.

                            
Target TypeTarget Value Data TypeReference/Actual Value
CountryNumeric

Reference Value.  id attribute from the response returned byhttp://$URI_PREFIX/api/common/geo API

Region/StateNumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
CityNumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
DMANumericReference Value.  id attribute from the response returned by Commonhttp://$URI_PREFIX/api/common/geo API
excludeBooleanYes

Default will be false.

Valid values can be true or false

The exclude parameter defines the behavior of targeting. By default specified targetLevel and targetValue will be included as exclude will be false.

You can either include or exclude the entities during targeting for given line time for entities at same level. E.g. You can include Country as United State but none of other countries you can exclude which will create a conflict during LineItem targeting.

However you can exclude states, cities from United state if want.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/geos/ 

 

Response

Sample Response JSON

The Response will not return target level for Zip/Postal Codes

{
    "targets": [
        {
            "targetValue": 162908,
            "exclude": false,
            "targetLevel": 2,
            "countryCode": "US",
            "cityName": "Virgin Islands",
            "dmaCode": 0
        },
        {
            "targetValue": 5818,
            "exclude": false,
            "targetLevel": 3,
            "countryCode": "IN",
            "cityName": "Pune",
            "dmaCode": 0
        },
        {
            "targetValue": 162688,
            "exclude": true,
            "targetLevel": 4,
            "countryCode": "US",
            "cityName": "New York",
            "dmaCode": 501
        },
        {
            "targetValue": 107,
            "exclude": true,
            "targetLevel": 1,
            "countryCode": "IN",
            "cityName": "India",
            "dmaCode": 0
        },
        {
            "targetValue": "P10036",
            "exclude": false
        }
    ]
}

 

Error Codes for Geography Targeting

Error codes will be displayed with row information. Row indicates the order of the target object in the request.

                                 

Sr. NoError CodesError MessageDescription
1.PH_ACESS_DENIEDAccess DeniedWhen the provided lineitemid does not exist or you do not have access to a line item to perform the edit operation.
2.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or empty target value
3.PH_MISSING_OR_INVALID PARAMETER_MSGMissing or Invalid Target LevelWhen any target object contains NULL or empty target level
4.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid entity id [1442]When Invalid Line Item Id is provided in the request

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

Verseion 0.1

Attachments

    Outcomes