GPS targeting is a targeting type that allows users to select geographical areas on a map in the booking interface, or as GPS coordinates in the API. For ad requests specifying a GPS position (as latitude and longitude) deemed to be inside one of the targeted areas, campaigns/creatives with this type of targeting will match. For ad requests not specifying a GPS position, the targeting will never match.
Throughout the system, positions are always given as decimal degrees using the WGS 84 coordinate frame, as used by the GPS standard. Distances are given as a difference in degrees. Note that this does not correspond to geodesic distances (i.e. straight line distances on the Earth’s surface)!
Targeting and availability checks
The booking interface allows the user to draw/select areas on a map when booking targeting or making availability checks. The Geo targeting section has been changed in the interface so that it now has two subsections:
- GPS targeting
- Geo targeting based on IP addresses.
We combined the two targeting types in the GUI as GPS targeting overrides targeting by IP if the request contains a GPS position. The map allows the user to navigate to correct locations and zoom in/out on the map. The user can create 3 types of areas:
- Polygon (supports complex polygons)
- Geodesic circle (radius given as degrees)
A geodesic circle is a circle with equal distance, in meters, to center. There is no such thing as a real circle in OpenLayers so we approximate it with a 36 vertices regular polygon.
Each area may be given a name that is used in the targeting sidebar view, and to identify it in reports. Upon creating an area the user is prompted for a name (defaults to “No name yet” but can also be renamed later on). Existing areas can also be removed. No functionality for altering or moving the areas are currently in place. The booking interface uses OpenStreetMap, which is community-driven, where users contribute with map data.
The booking interface and API limits the number of areas to 10 and the number of vertices for polygons to 40.
The reporting interface presents the logged GPS positions as a list of the currently booked area names containing the logged positions, with a row for each area. Currently there is only reporting on the campaign side.
Reports also contain a “Summary” row listing the amount of total traffic with logged GPS positions. This is not a summary of the traffic in the other rows, as one position may match multiple areas (in case of overlap), or none (in case of excluding targeting or changed areas). It is also not necessarily the summary of all traffic on the campaign, as it may previously have been booked without GPS targeting.
On reports covering multiple campaigns, it is possible that differently defined areas share the same name. Traffic for these will all be summed into the same report row. If this proves to be a problem for users the rows will have to be indexed by some other means.
The ad request should contain two URL query parameters lat= and lon=, where the values are assumed to be WGS 84 coordinates given as a floating point string representation. Both parameters must be given and contain valid numbers (-90 to 90 for latitude, -180 to 180 for longitude) for the position to be passed for targeting checking.
When using the Mobile SDK's GPS coordinates will be passed in the request automatically.
GPS forecasting is based on calculating soft weights. This is because we believe that samples would provide a poor distribution of points for many situations, due to people’s moving patterns throughout the day. The soft weight calculated is based on the GPS log files for content units, taking each point in the file and comparing whether it matches the given GPS areas or not. The ratio of matching points to total amount of impressions for the given file (this is not simply the sum of impressions with GPS positions, but all impressions, as impressions without a GPS position always result in a non-matching campaign).
Booking and forecasting
To book GPS targeting parameters in the API, or to define them in availability checks, the parameters to use are:
- areaNameX where 0 ⇐ X ⇐ GPS_TARGETING_MAX_NO_AREAS
- areaTypeX where 0 ⇐ X ⇐ GPS_TARGETING_MAX_NO_AREAS
Area names may not contain any | characters, a limitation imposed by the current database format. If areaNameN isn’t found it’s assumed that any area above N isn’t specified. So if areaName4 isn't found, the API doesn’t check for 5 or above.
Area types must be rectangle, circle or polygon.
For rectangles, two points are necessary:
- northwestX for the northwest corner of the rectangle
- southeastX for the southeast corner of the rectangle
The points are given as lat, lon floating point numbers and must be within the allowed ranges for latitudes and longitudes, and with the correct relative positioning.
For circles, the following parameters are necessary:
- centerX for the center point of the circle
- radiusX for the circle’s radius (in degrees)
The radius must be positive and larger than 0.
For polygons, the following parameter is necessary:
- pointsX for the polygon’s points
The points are given as lat1,lon1,lat2,lon2,lat3,lon3,… for up to GPS_TARGETING_MAX_NO_VERTICES points.
API reporting is available for campaigns using the cmd=statistics&what=campaign&type=gps query parameters.