Hyper Local Targeting

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

Description

Use Hyper Local Targeting API to target the Line Item from Central Location coordinates and the given radius in miles and kilometers.

Important Note:

  1. This API validate the latitude ( -90 to 90 ) and longitude -180 to 180 range only.
  2. This API only support area inclusion and not exclusion.

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/hyperlocaltargetingsPOSTAdd/Remove/Update Hyper Local targeting for the Line ItemConfigure Hyper Local Targeting
/lineitems/{lineItemid}/targets/hyperlocaltargetingsGETRetrieve Hyper Local targeting Details for a line itemRetrieve targeted Hyper Local targeting for a Line Item

 

Configure Hyper Local Targeting

Overview

This API enables you to add, update or remove Hyper Local Targeting 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
targetValueObject

Yes

Should not be null.

Should not be empty.

Target Value will contain the following attributes:  

  1. Valid range of latitude.
  2. Valid range of longitude.
  3. Radius units must be "km" or "mi"
excludeBooleanYes

Default will be false.

This API does not allow you to set the exclude as true since targeting on location only allows include.

If you pass exclude with true, the API does not honor it and silently ignores it.

Sample Request URL

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

Sample Request JSON

    

{
    "targets": [{
        "targetValue": {
            "latitude": 40.7127837,
            "longitude": -74.0059413,
            "radius": "0.5",
            "radiusUnit": "mi"
        },
        "exclude": false
    }]
}

 

Sample Response JSON

 

{
    "entity": {
        "id": { targetid associated with lineitem },
        "isPreset": 0
    },
    "targets": [{
        "targetValue": {
            "latitude": 40.71278370,
            "longitude": -74.00594130,
            "radius": 0.5000,
            "radiusUnit": "mi"
        },
        "exclude": false
    }]
}

 

Retrieve Targeted Hyper Local Targeting for a Line Item

Overview

This API enables you to retrieve Hyper Local Targeting Details 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
targetValueObject

Yes

Should not be null.

Should not be empty.

Target Value will contain the following attributes:  

  1. Valid range of latitude.
  2. Valid range of longitude.
  3. Radius units must be "km" or "mi"
excludeBooleanYes

Default will be false.

This API does not allow you to set the exclude as true since targeting on location only allows include.

If you pass exclude with true, the API does not honor it and silently ignores it.

Sample Request URL

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

Sample Response JSON

    

{
    "targets": [{
        "targetValue": {
            "latitude": 40.71278370,
            "longitude": -74.00594130,
            "radius": 0.5000,
            "radiusUnit": "mi"
        },
        "exclude": false
    }]
}

 

Error Codes for Hyper Local 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_ACCESS_DENIEDAccess Denied.When the provided lineitemid does not exist or you do not have access to the line item to perform the edit operation.
2.PH_MISSING_OR_INVALID_PARAMETER
  1. Missing or Invalid Target Value
  2. Missing or Invalid radius unit.
  3. Missing or Invalid latitude.
  4. Missing or Invalid longitude.
  5. Missing or Invalid radius.
  1. When any target object contains NULL or empty target value
  2. When radiusUnit is not either mi / km.
  3. When latitude is not in valid range.
  4. When longitude is not in valid range.
  5. When user is passing 0 as radius

 

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