Geopath API Public DocumentationVersion 2.2 Release Notes

Version 2.2 Release Notes

v2.2.5 2023-09-01 – Change Summary

  • In a small percentage of scenarios, metrics for an /inventory/plan could change slightly due to small differences in spot selection as a result of spots not qualifying for plan inclusion due to their Geopath audit status.

  • Spots specified in the optional /inventory/plan include_spots lists will be included in the plan in the order that they are specified in the include_spots list, before any other spots are included to meet the plan goal. Previous to this change, the order of included_spots was not guaranteed.

  • Endpoints (e.g., /inventory/search or /inventory/plans ) that support specification of an audience base_segment, did not ensure the combination of audience base_segment and audience target_segment are compatible. Incompatible combinations of base_segment and target_segment now return an error. In conjunction with enforcing allowable base_segments for a target_segment, we have enabled all audience segments to be their own base_segment.

  • When a spot lock is included as part of a media_type_group specification in /inventory/plans, and if the spot lock value is greater than the total spots available in the requested geography, then /inventory/plans incorrectly returned the lock value as total spots in the market. 

  • Inclusion of the fieldset parameter caused some /inventory/search/named requests to fail in offline mode.

  • /inventory/search/named and /inventory/search/summary did not report errors when an inventory_market_list attribute contained invalid geography identifiers, and instead would silently remove the invalid geography, potentially falling back to all inventory if no valid geography identifiers were specified. Inventory Market list will now return an error when an invalid market list is included in an API request.

 

v2.2.4 2023-07-14 – Change Summary

The following issues have been corrected:

  • When certain roadside panel types were used in market plan (inventory/plans), audience measures were not returned

  • When certain scheduled fleet networks were used in market plan (inventory/plans), negative audience measure values were returned

  • When adding 3 or more separate media types to a market plan (inventory/plans), results were not returned

  • When adding media class, structure type, and media types to either a market plan (inventory/plans) or the Explore module (inventory/search/summary), results were not returned

  • When performing inventory plans (inventory/measures/summary) for certain CBSAs, audience measures were not returned

  • In some scenarios, reach & frequency measures for roadside units reported by inventory/measures/summary were not aligned with inventory/search/summary

  • Using the market plan API endpoint (inventory/plan) to lock TRP values at 0 disregards the lock altogether

  • Applied data patches to update reach and frequency measures for roadside and transit station inventory that were returning unexpected results for some members. Please click here for a list of updated media.

Please note: inventory plans run for roadside and transit media between June 26-28, 2023 may have returned unexpected results; we recommend rerunning any plans run during that 3-day period.

v2.2.3 2023-05-25 – Change Summary

The following issues have been corrected:

  • When the requested target_geography is “local_dma” /inventory/search/summary incorrectly reported reach_net and reach_percent

  • Optimizations were made to /inventory/search/summary to allow some complex summary_level_list values to complete without a gateway timeout

  • /inventory/plans and inventory/search/summary returned incorrect reach values for a single advertising unit

  • The wrong segment name was displayed in some instances in the /measures/summary/segments endpoint

  • inventory/measures/summary returned a 500 error when measures were requested for spots and audiences combinations with zero reach_net

  • /inventory/search/summary returned a 500 error when a summary_level_list for a large number of spots and many summary levels was requested

v2.2.2 2023-05-04 – Change Summary

API response times for larger /inventory/search/summary and /inventory/measures/summary aggregation requests have improved by 5-10 seconds (on average).

  • Passing arrays of SOME spots into inventory/measures/summary causes all spots to return as 'spots with no measures'

Corrected an issue when requesting measures for a mix of spots some with available measures and some without. Now spots with no measures available return a list of spots with out measures and measures for a list of spots with available measures, instead of returning no measures for any spot.

  • /inventory/measures/summary queries timeout with > 7-10 batches

Optimized /inventory/measures/summary so that many more batches of spot can be submitted than previously supported without returning a gateway timeout. Previously to this change, the /inventory/measures/summary endpoint could not support more than approximately 7-10 batches of spots without timing out. The maximum number of batches supported after this change depends on the number of simultaneous /inventory/measures/summary requests in progress and the number of batches in each.

  • Roadside shows high frequency and low reach for digital urban panels

Corrected an issue in /inventory/plans where was causing lower than the correct reach values for plans that encompassed multiple target geographies with roadside inventory.

  • Fleet market plans shows 30% reach in NY DMA and 17.1% reach in 5 Boroughs for same inventory

Corrected an issue where /inventory/plans returned incorrect reach for plans that encompassed multiple target geographies with fleet inventory.

  • /inventory/plans does not align with inventory/search/summary at interpolation points

Corrected an issue where /inventory/plans was incorrectly returning reach values for roadside inventory.

  • /inventory/summary/measures does not allow identical start and end timestamps to represent a single day

Ensured that identical start and end timestamps at midnight return measures for a single day instead of returning no measures.

  • Some spots return incorrect status

Corrected status values for some spots that were not in “published - measured” status.

  • Fleet plan market reach values don't match search summary for the equivalent plan

Corrected issue with some fleet market plans where some low net reach values were showing incorrect reach percents.

  • /measures/summary/segments is not sorting correctly

Corrected sorting issue where /measures/summary/segments did not sort audience segments by index_comp_target values.

  • Improve fleet reach accuracy for groups with many advertising units

Improved accuracy of reach calculations for fleet based media that were returning excessively high reach and lower average frequency values due to inaccurately accounting for impression duplication when several hundred or more units of fleet advertising were included in a market plan (i.e. /inventory/plans) request.

  • Summary_level_list["Place"] variations returns different measures for same place

Corrected reach_net values in /inventory/search/summary when using the “summary_level_list” attribute and summarizing by “place” and other summary values.

v2.2.1 2023-03-22 – Change Summary

Passing an array of spot IDs into the /inventory/summary/measures endpoint that are not be in ‘published-measured’ or ‘published-under review’ status should return summarized measures that include ONLY the spots in ‘published-measured’ or ‘published-under review’ status, rather than return a 500 error.

  • Add support for representation type name list criteria to plans endpoint

Plans endpoint /inventory/plans does not support representation type as a criterion in the request while /search/summary endpoint does support this representation type as a filter.

  • Querying batches including spots with very low-reach via inventory/measures/summary triggers 500 error

Queries to inventory/measures/summary that included spots with low-reach and/or no-reach spots returned a 500 error. This has been corrected so that collections of spots in /measures/summary with no-reach will return correct measures for all spots.

  • Increase consistency of calculated reach for increasing number of spots in a roadside group

The roadside machine learning reach prediction was re-trained to consider groups of spots that contain other groups as proper subsets in order to increase the consistency of reach predictions when the size of a package is increased as input to /inventory/search/summary, /inventory/plans, and /inventory/measures/summary.

  • Inventory/search/summary with single spot has null DMA in summary

When an /inventory/search/summary has a single spot in the request spot list and summarizes by DMA the DMA summary has null values. This has been corrected so that single spots in a DMA summary no longer return null values.

  • Market plans reach can exceed market saturation threshold with very large packages

Both /inventory/search/summary and /inventory/plan now apply a reach market saturation threshold that is no more than 85% of the population for all contributing census blocks is included in the reach/frequency calculation. Prior to this change, the reach market saturation point was computed correctly by /inventory/search/summary, but was not computed correctly by /inventory/plans.

v2.2 2023-02-27 – Initial Production Release

Please note that data returned from the v2.2 API is not guaranteed to be accurate or stable until 2/27/23 and will ONLY support the 2023 data set (not the 2021R1 data set). Please be advised that 2023 data from Geopath’s API v2.2 staging environment should not be used in production environments or for transactional purposes, but will be made available in the staging environment by 1/6/23 (at which point a code freeze will be put into effect). Please see https://geopath.atlassian.net/wiki/spaces/GEOP/pages/2221473793 for the most updated list of known API v2.2 issues.

Executive Summary of Breaking Changes (please refer to this document for a detailed list of field-level impacts by API endpoint)

  • Removed Support for 2020 and 2021 forecast measures.

  • Deprecation of "measures" object in favor of "measures_list" array which can support multiple objects. 

  • Deprecation of “total_msg_impressions” object in favor of “total_msg_impressions_list” array which can support multiple objects.

  • Deprecation of the "measures_release" parameter in favor of the "product_name" parameter.

    • Note: ​Providing the "measures_release" parameter will be like sending extraneous information, which will cause the endpoints to respond with default behavior (which is to return data for the default data product).

  • Deprecation of the "inventory/summary/search" endpoint in favor of "inventory/search/summary" endpoint.

  • Removed support for using "global" as a market or as the default in market plans.

    • Note: The plans endpoint will now return an error when no market is provided

  • Deprecation of "measures" parameter in GET by ID endpoints in favor of new frame and spot measures parameters.

    • Note: Passing a "measures=true" or "measures=false" parameter will be like sending extraneous information, causing the endpoints to respond with default behavior (which is to return only spot measures). Users will need to pass "spot_measures=false" to return an API response with no measures at all. 

  • Deprecation of "measures_required" attribute in POST search endpoints and "measures/summary" endpoint in favor of new frame and spot measures parameters.

    • Note: Passing a "measures_required=true" or "measures_required=false" parameter will be like sending extraneous information, causing the endpoints to respond with default behavior (which is to return only spot measures). Users will need to pass "spot_measures=false" to return a response with no measures at all. 

  • Deprecation of the "place_type" object within the "location" object of a response, which will be replaced with a "place_types" array that will support multiple objects. 

  • Deprecation of the "segments/segment_search" endpoint in favor of an updated "segments/search" endpoint

  • Addition of pagination to "segments/search" endpoint

    • Note: Previously, API responses from this endpoint did not paginate. Now, for responses greater than 5,000 objects, the response will be split into multiple pages

  • Changes to the POST "inventory/search" response to better match the GET "inventory/<frame_id>" response.

    • Change of "media_status" to "status_type"

    • Addition of new "construction" object which includes details and location of the construction record associated to the frame. 

      • Existing "construction_type" object will now be located within the "construction" object.

    • Removal of "spot_references" array in favor of full inventory model of a "layouts" array, which includes a "faces" array, which includes a "spots" array.

      • Measures data still available on each record in the "spots" array as part of the "measures_list" array

      • Each of these inventory data arrays includes its own "representation" array

  • Deprecation of “plant_frame_id”,”publisher_unique_face_id”,”plant_spot_id” and “publisher_unique_id” fields in responses, in favor of new fields on the representation object of each inventory level.

    • Each representation record will now support two alias ID fields, primary and secondary, where that account’s identifiers for that inventory record can be stored.

      • plant_frame_id in API v2.1 has become frame_id_alias_primary in API v2.2

      • plant_spot_id in API v2.1 has become spot_id_alias_primary in API v2.2

      • publisher_unique_id in API v2.1 has become spot_id_alias_secondary in API v2.2

      • publisher_unique_face_id in API v2.1 has become face_id_alias_primary in API v2.2

  • Operator_name_list and plant_name_list attributes name have been removed and superseded by parent_account_name_list and account_name list. The two new alternative attributes represent two separate levels of inventory ownership: parent_account_name_list represents the owner of the inventory, account_name_list represents the manager of the inventory.

  • Changes to GET “inventory/<frame_id” response to better match the POST “inventory/search” response.

    • Change of “id” to “frame_id”

    • Change of “full_motion” to “frame_full_motion”

    • Change of “partial_motion” to “frame_partial_motion”

    • Change of “rotating” to “frame_rotating”

    • Change of “interactive” to “frame_interactive”

    • Change of “audio” to “frame_audio”

    • Change of “id” to “spot_id” (under spot object)

    • Change of “full_motion” to “spot_full_motion” (under spot object)

    • Change of “partial_motion” to “spot_partial_motion” (under spot object)

    • Change of “rotating” to “spot_rotating” (under spot object)

    • Change of “interactive” to “spot_interactive” (under spot object)

    • Change of “audio” to “spot_audio” (under spot object)

    • Change of “share_of_voice” to “spot_share_of_voice” (under spot object)

  • The "eff_freq_min", "eff_freq_avg", "eff_reach_net", and "eff_reach_pct" fields representing ‘effective frequency and effective reach’ have been set to return ‘null’ values by design for this initial v2.2 release.

​​​New Features
 

  • Added support for Reach based goals for market plans. Market plans can now provide audience measures for plan objectives expressed as either "reach_pct" and "reach_net".

  • Added support for total frame measures.

    • ​Users will be able to use "frame_measures=true" parameter or GET endpoint URLs and POST endpoint request bodies

    • These frame level measures will be provided in a “measures_list” object that is present on the frame level of the response in addition to any spot level measures.

  • Added support of "max_frames" request attribute.

    • To better support transit and place based inventory, max_frames will allow operators to provide a single representative frame record along with a number that indicates how many of these identical frames are within a place. Using the the "max_frames" attribute in the API can then help aggregate the total measures across all those frames in a given place. 

    • While currently supported in the API, this feature is still pending wider data availability.

  • ​​Added support for "reach_freq" parameter in requests.

    • ​Can be set for True or False, allowing a user to limit measures to non Reach / Frequency related measures which should return faster. 

  • Added support for named offline searches which allows for users to create their own saved bulk API queries.

    • Users will need to authenticate their credentials and provide an Authorization Header in their requests to these new endpoints

      • Added new User API product

        • Includes /user/login POST endpoint, which takes the user email/password to provide an access token to be used elsewhere in the API

    • New /inventory/search/named endpoint allows a user to add an “offline”: true parameter to the request along with a “name” parameter

      • This will return a URL with a unique ID that can be used to retrieve the request when it is completed running.

    • Additional endpoints added to aid in finding, refreshing and deleting these saved requests.

      • GET (retrieve) /inventory/search/{search_id}

      • POST (refresh) /inventory/search/{search_id}

      • DELETE /inventory/search/{search_id}

      • GET (list) inventory/named/list

    • These endpoints create data that matches the output of the inventory/search endpoint and can use the same filtering and request body format.

    • Note: while the v2.2 API is in staging, these saved searches will be lost with every bi-weekly data release as the staging database is refreshed each time. The ability to use this ‘saved search’ is meant only for testing and should not be used in production services.

    • More information on this can be found at this Use Case

  • Added support of Usage tracking within the API

    • /user/usage endpoint can provide data on the usage of a provided API key

    • This allows users to better track their API usage by a set of given metrics.