Zip 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 Zip Targeting API to target the line item on zip code belong to specific country. While targeting zip codes, the country code is mandatory which you can retrieved using http://$URI_PREFIX/api/common/geo?filters=geoLevel eq 1&showAll=true

Important Note:

  1. Zip targeting API validates the provided zip code against the country code. If zip code does not exist against the given country code, it will fail entire zip targeting call.  You should pass only valid set of zip codes where you want to target the line item.
  2. User should make sure that same targetValues are not getting included / excluded at 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)

Supported Operations

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/zipcodesPOSTAdd/Remove/Update zip targeting for a Line ItemConfigure Zip/Postal Codes
/lineitems/{lineItemid}/targets/zipcodesGETRetrieve the Details of the Zip/Postal codes targeted for a Line ItemRetrieve Targeted Zip/Postal Codes for a Line Item

 

Configure Zip/Postal Codes

Overview

This API enables you to add, update or remove zip/postal codes 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 zip codes for given country/state and set against the Line Item.

The following are valid Target Levels for Geography Targeting:

               
Target LevelTargetDescriptionSample URL
5ZipZip/Postal Code

You can retrieve the supported zip codes by applying country/state level filter.

Example: Get the list of zip codes available in the system for Country  "United States" and State "New York"

https://$URI_PREFIX/api/common/zipcode?filters=countryCode EQ US&filters=regionCode EQ NY&pageNumber=1&pageSize=100

Since there are a large number of records at country/state level, you should use pagination and applicable filters to get a faster response.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual  Zip Code and Country Code value. 

If you are doing Zip / Postal code level targeting (target level = 5) then target value should be actual zip code received in the https://$URI_PREFIX/api/common/zipcode API.

 
e.g. If you want to target for zip code for United States 

  1.  Actual Zip Code
  2. 2 letter ISO Country Code

Following are the supported data types

                  
Target TypeTarget Value Data TypeReference/Actual Value
Zip/Postal CodeString

Actual zip code

countryCodeString2 letter ISO country code
excludeBooleanYes

Default will be false.

Valid values can be true or false

This value indicates whether the zip code is to be included/excluded while targeting a Line Item. 

Sample Request URL

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

Sample Request JSON

{
    "targets": [{
        "targetValue": {
            "code": "13036",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5
    }, {
        "targetValue": {
            "code": "13411",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5
    }, {
        "targetValue": {
            "code": "11040",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5
    }, {
        "targetValue": {
            "code": "411036",
            "countryCode": "IN"
        },
        "exclude": false,
        "targetLevel": 5
    }]
}

Sample Request JSON: To Remove all Zip/Postal Code Targeting for a Line Item

{
    "targets": []
}

Response

Sample Response JSON

    

{
    "entity": {
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "targetValue": {
            "code": "13036",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "Central Square",
        "code": "13036",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "13411",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "New Berlin",
        "code": "13411",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "11040",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "New Hyde Park",
        "code": "11040",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "411036",
            "countryCode": "IN"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "India",
        "regionName": "Maharashtra",
        "city": "Pune",
        "code": "411036",
        "countryCode": "IN"
    }]
}

Retrieve Targeted Zip/Postal Codes for a Line Item

Overview

This API enables you to retrieve targeted zip/postal codes 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 zip codes for given country/state and set against the Line Item.

The following are valid Target Levels for Geography Targeting:

               
Target LevelTargetDescriptionSample URL
5ZipZip/Postal Code

You can retrieve the supported zip codes by applying country/state level filter.

Example: Get the list of zip codes available in the system for Country  "United States" and State "New York"

https://$URI_PREFIX/api/common/zipcode?filters=countryCode EQ US&filters=regionCode EQ NY&pageNumber=1&pageSize=100

Since there are a large number of records at country/state level, you should use pagination and applicable filters to get a faster response.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual  Zip Code and Country Code value. 

If you are doing Zip / Postal code level targeting (target level = 5) then target value should be actual zip code received in the https://$URI_PREFIX/api/common/zipcode API.

 
e.g. If you want to target for zip code for United States 

  1.  Actual Zip Code
  2. 2 letter ISO Country Code

Following are the supported data types

                  
Target TypeTarget Value Data TypeReference/Actual Value
Zip/Postal CodeString

Actual zip code

countryCodeString2 letter ISO country code
excludeBooleanYes

Default will be false.

Valid values can be true or false

This value indicates whether the zip code is to be included/excluded while targeting a Line Item. 

Sample Request URL

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

Response

Sample Response JSON

    

{
    "targets": [{
        "targetValue": {
            "code": "13036",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "Central Square",
        "code": "13036",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "13411",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "New Berlin",
        "code": "13411",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "11040",
            "countryCode": "US"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "United States",
        "regionName": "New York",
        "city": "New Hyde Park",
        "code": "11040",
        "countryCode": "US"
    }, {
        "targetValue": {
            "code": "411036",
            "countryCode": "IN"
        },
        "exclude": false,
        "targetLevel": 5,
        "country": "India",
        "regionName": "Maharashtra",
        "city": "Pune",
        "code": "411036",
        "countryCode": "IN"
    }]
}

Error Codes for Zip/Postal Code Targeting

                           

Sr. NoError CodesError MessageDescription
1.PH_ACCESS_DENIEDAccess DeniedWhen an invalid Line Item Id is provided in the request
2.PH_MISSING_OR_INVALID_PARAMETER
  1. Missing or Invalid Target Value
  2. Missing or Invalid Target Level
  3. Missing or Invalid countryCode
  4. Missing or Invalid Zip Code
  1. When any target object contains NULL or empty target value
  2. When specified wrong target Level
  3. When Invalid Country Code is provided
  4. When Invalid Zip Code is Provided for country
3.PH_DUPLICATE_ENTRIES_FOUNDDuplicate Zip Code IdWhen user includes the same zip during targeting.

 

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

Version 0.1

Attachments

    Outcomes