Hyper Local Data Source Targeting (UAS)

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

Description

Use the Hyper Local Data Source Targeting API to target the Line Item on Inventory containing the location coordinates derived by various techniques like GPS, IP address or user-provided, etc.

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

Supported Operations

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/hyperlocaldatasourcesPOSTAdd/Update/Remove Hyper Local Data Source Targeting for a Line ItemConfigure Hyper Local Data Source Targeting
/lineitems/{lineItemid}/targets/hyperlocaldatasourcesGETRetrieve Hyper Local Data Source Targeting Details if applied to a Line ItemRetrieve Hyper Local Data Source Targeted for a Line Item

 

Configure Hyper Local Source Targeting

Overview

This API enables you to add, update or remove Hyper Local Data Source for a Line Item.

Request

           

URIHTTP Method
https://$URI_/PREFIX/{apiVersion}/phoenix//lineitems/{lineItemId}/targets/hyperlocaldatasourcesPOST

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

This API accepts array of target objects, where each object must contain the following attributes.

                        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Hyper Local has only a single target level, therefore it is requested to pass 1 during targeting. If you passed an invalid targetLevel API will silently ignore this.

You can retrieve the supported data source that may be used to get the location.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

Retrieve the supported data source, which you may use to retrieve the location.

http://$URI_PREFIX/common/hyperlocaldatasource

 e.g. If you want to target line item only on GPS based location coordinates, then you should set 1.

 

                       
Reference/Actual ValueData SourceDescription
1GPS/Location Servies

If you want to target a Line Item only GPS derived Location coordinates.

2IP AddressIf you want to target a Line Item on IP address derived from Location coordinates such as Max Mind, etc.
3User ProvidedIf you want to target the Line Item on Location Coordinates if provided by the user, based on registration Data.

Sample Request URL

https://$URI_PREFIX/{apiVersion}/phoenix/lineitems/{lineItemId}/targets/hyperlocaldatasources/

Sample Request JSON

    

 {
    "targets": [{
        "targetValue": 1,
        "targetLevel": 1
    }]
}

Sample Response JSONResponse

    

{
    "entity": {
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "targetValue": 1,
        "exclude": false,
        "targetLevel": 1
    }]
}

Retrieve Hyper Local Data Source Targeted for a Line Item

Overview

This API enables you to retrieve Hyper Local Data Source for a Line Item.

Request

           

URIHTTP Method
https://$URI_/PREFIX/{apiVersion}/phoenix//lineitems/{lineItemId}/targets/hyperlocaldatasourcesGET

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

This API accepts array of target objects, where each object must contain the following attributes.

                        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Hyper Local has only a single target level, therefore it is requested to pass 1 during targeting. If you passed an invalid targetLevel API will silently ignore this.

You can retrieve the supported data source that may be used to get the location.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

Retrieve the supported data source, which you may use to retrieve the location.

http://$URI_PREFIX/common/hyperlocaldatasource

 e.g. If you want to target line item only on GPS based location coordinates, then you should set 1.

 

                       
Reference/Actual ValueData SourceDescription
1GPS/Location Servies

If you want to target a Line Item only GPS derived Location coordinates.

2IP AddressIf you want to target a Line Item on IP address derived from Location coordinates such as Max Mind, etc.
3User ProvidedIf you want to target the Line Item on Location Coordinates if provided by the user, based on registration Data.

Sample Request URL

https://$URI_PREFIX/{apiVersion}/phoenix/lineitems/{lineItemId}/targets/hyperlocaldatasources/

Response

Sample Response JSON

    

{
    "targets": [{
        "targetValue": 1,
        "exclude": false,
        "targetLevel": 1
    }]
}

References

HTTP Status Codes 

 

Error Codes for Hyper Local Data Source Targeting

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

                       

Sr. NoError CodesDescription
1.PH_ACCESS_DENIEDThis error occurs when the lineitemid provided does not exist or you do not have access of the line item to perform the edit operation.
2.PH_MISSING_OR_INVALID_PARAMETERThis error occurs when any target object contains NULL or empty target value or an invalid value.
3.PH_DUPLICATE_ENTRIES_FOUNDThis error occurs when any target value is duplicated in the POST request.

 

Version 0.1

Attachments

    Outcomes