Location REST API

This API exposes operations to allow management of the geotargeting data made available to Advertisers on their Campaigns within the cX::ad platform.

This API allows a Broker to define the Ontology (eg. Country, State, City) and a graph of geographical Locations themselves that Advertisers can choose from when deciding how their Advertisements should be targeted.

Domain Model

The locations data is maintained in a LocationRepository. Each broker has a unique LocationRepository that can be edited only by that broker. The LocationRepository contains two types of data:

1. An ontology (or meta-data) of location types

2. A graph of inter-related locations

Location ontologies

The ontology maintains a set of LocationTypes. Each LocationType consist of a location level and locale-specific labels for the type.

A location's level is simply a positive integer that indicates its hierarchy. Locations that are hierarchically higher will have lower level values. The example table below demonstrates the ontology of a broker that has three levels and has supplied alternate labels in two languages (Hindi and French). Note that this is only an example, brokers may setup their own ontologies with as many levels as is appropriate for their target geographical areas. They may also use whatever language is appropriate for the default and alternate labels.

Examples:

Note that you can have multiple types at the same level. Note also that, because LocationRepositories are broker-specific, different brokers will maintain their own ontologies.

Locations

Location entities represent a unique geographical location. Locations are uniquely identified by an id. This id is generated by cX::ad's UniqueIdentifier class which is really only a wrapper for UUIDs - a sequence of 32 hex characters. In fact, if you want to generate a UUID outside of cX::ad (for e.g. when calling the REST calls from non-Java clients) you can simply use any of the available methods to generate UUIDs to generate valid location ids. So, for e.g., on a system with the uuid command installed you can generate a valid location id like so:

$ uuid -v 4|sed 's/-//g'
f852e9ae057211dfbd8e00241d142669

Note that the output of uuid has been piped to sed simply to remove the '-' chars generated by the Linux version of the uuid program.

Locations are typed as they contain a reference to a valid location type in the broker's location ontology and as a consequence they are also hierarchical, based on the level of the LocationTypes they refer to. Additionally, like the LocationType, the Location entity has a default label as well as a localised label.

Examples

Relationships

Locations can be related to each other. This is annotated against the location with the id of the location related to. There are three types of relationships, the table below lists them as well as their meaning for the location which they annotate against the location it relates to.

Querying the Ad Server

Once your ontology is set up, the 'l=<location name>' attribute can be passed to the ad server from an ad space requesting ads.  Here are some important things to note:

• cX::ad does use Locales when retrieving Locations.  It returns any Location that has a Label that matches the value passed in by the 'l=' parameter.

• You can create new Locales to allow for different variants of Location names, within the one language.

• Locales are used by the UI when deciding what Labels to display to the user, when specifying geo-targeting.  This is based on the user's locale preference.

Persistence Store

Both the ontology and the locations are stored on a per-broker basis. To be able to manipulate them you should use the relevant methods in the LocationService implementation. Alternatively you can also use the REST API.

REST API

The Location Service's REST API exposes three different resources:

The following sections detail the API for each resource type. Note that the URL columns only contain the suffix of the URL after the main URL context for the API. Also note that the parts of the URLs in square brackets represent variables. There are only two permissible variables:

• [brokerId] - the broker's unique id - this matches the id of the broker's BrokerContainer document.

• [locationId] - a location's unique id.

Label entry order is significant

A <labels> entry forms a HashMap of localeEntry elements with the <locale> as the key. PUT and POST methods expect the order defined in the localeEntry child sequence (cxad.xsd):

In the code example below:

1. key=fr

2. value=Pays

Label Entry

<cxad:entry>
  <cxad:locale>fr</cxad:locale>
  <cxad:string>Pays</cxad:string>
</cxad:entry>

The <locale> element must be the first in the sequence as defined by cxad.xsd.

LocationOntologyResource

A LocationOntologyResource is PUT in the form of a single XML data file for the full ontology. The below ontology-broker1.xml file serves as an example.

ontology-broker1.xml

LocationResource

A LocationResource is PUT in the form of a single XML data file for the location. The below location-Australia.xml file serves as an example.

location-Australia.xml

LocationsResource

The LocationsResource is really an aggregating resource - referring to all the locations in a particular broker's location graph. As such you cannot PUT to it, however, you can POST multiple locations to it in bulk. The locations are to be sent in XML form. The location ontology is PUT into the LocationOntologyResource as a single XML data file. The below locations.xml file serves as an example.

locations.xml

Security

Security in the API is based on the standard cXad security service. The location ontology and graph for a broker are rooted at the context of the broker's BrokerContainer document.

Example demo scripts

A set of example location API demo scripts has been attached to this page below. You can download and view and/or run it if you wish. Note that the scripts require cURL to have been installed prior to running them.

location-REST-demo.tgz

Ad Matching Examples

(Note, 'Hungry St' is within Mossman (Suburb), is within Sydney (City), is within New South Wales (State), is within Australia (Country)

If an Advertiser sets matching criteria on an Ad or Campaign of KW: pizza, location: Sydney...

Searching

Once indexed, you can make GET calls to the adserver's Location Search REST API to do location searches:

Note: If you do use the APIs above to change the locations, those locations will have to be indexed before they will show using the adserver's Location Search. This is done automatically once per day.

https://{cxadbaseurl}/adserver/location/search/{brokerId}?lang=en&l=Richmond

Last updated: January 19, 2022