v2.2.11 2024-07-16 – Change Summary

• As of 6/28/24, an issue was corrected where /inventory/search results could not be returned on some pages when the page_size value (i.e. number of spots per page of results) was set to 1000 or greater

• An issue was corrected where queries sent to the inventory/search/named endpoint would not succeed if the count of spots that matched the dimensional inputs was greater than 1000

• An issue was corrected where queries sent to the inventory/search endpoint would not succeed if the volume of unique spot IDs used as input parameters was greater than 1425

• An issue was corrected where certain queries sent to the inventory/search/named endpoint would not succeed if the 2023 dataset was used

• An issue was corrected where certain queries sent to the inventory/plans endpoint would not use all spots in the market to fulfill the stated spot count goal

• An issue was corrected where certain queries sent to the inventory/plans endpoint would not allow users to input a specific count of spots above a certain threshold

v2.2.10 2024-06-17 – Change Summary

• As of 5/7/24, an issue was corrected where /inventory/measures/summary gave an incorrect target in-market population when measures for two or more spots was requested.

• As of 5/27/24, the ‘Current’ annual forecast for 2024 (known as ‘product_name’=20240301) became the default data product served via the API.

• An issue was corrected where /inventory/search/summary did not return the correct reach & frequency when the number of max_frames was greater than one (which impacts scheduled fleet spots as well as some place-based spots).

• An issue was corrected where /inventory/plans did not calculate reach & frequency correctly in some scenarios, depending on the target_geography_list and/or inventory_market_list and number of spots inputs used in the API request.

v2.2.9 2024-04-29 – Change Summary

• An updated annual forecast, labeled as the ‘Current’ data product in the UI and ‘product_name’=20240301 in the API, has been deployed to Production. The 2023 data product will continue to be the default data product used by the API until May 27, 2024 (at which point the 20240301 is scheduled to become the default data product).

• Corrected an issue in in place-based /inventory/plans when a large numbers of spots were included in the plan a small number of spots with low impression counts in the same market were not be available to be included in the same market plan.

• Previously, when a media operator requests Geopath to modify OOH asset attributes, those attributes were immediately returned by multiple endpoints including /inventory/search, inventory/{frame_id}, /inventory/spot/{spot_id}, etc. before the corresponding audience measures based on those updated inventory attributes were available. This caused the following issues:

  • When the count of place-based assets within a place were increased, these new assets were shown as ‘available’ but including them in an inventory plan did not increase the impressions or reach returned in the audience measures of the plan.

  • When a static to digital conversion occurred, or the number of spots in rotation was increased or decreased, hourly audience measures summed for an entire week did not equal the weekly audience measures for that inventory. This was due to spot length and spot share of voice values changing and being reported by API endpoints before the dependent total_msg_impressions value was recalculated during the monthly data release.

• Corrected an issue where place-based and scheduled fleet assets returned incorrectly low reach and high frequency when large numbers of spots were included in county-based target geographies

• Corrected an issue where frame-level API results across endpoints (e.g., /inventory/{frame_id}, /inventory/search, etc) always returned a “null” value for the frame ‘last updated date and time’ field (updated_dtm)

• As of 4/29/24, all inventory metadata returned by the API is now data-product specific and reflects the state of the inventory at the time the most recent audience measures were generated. Therefore, when retrieving data using the ‘Previous’ annual planning dataset (known in the API as ‘product_name’ = 2023), all API endpoints will return inventory metadata that represents the inventory as it existed in mid-November 2023 (which was when the last set of audience measures were calculated for the ‘Previous’ 2023 annual planning dataset) rather than returning inventory metadata that represents how the inventory exists in the present day.

v2.2.8 2024-03-11 – Change Summary

• Corrected an issue where the /inventory/plans endpoint incorrectly calculated reach and frequency numbers for roadside inventory in a limited number of scenarios.

• For multiple endpoints the attribute “market” in the JSON response now returns the “inventory_market_list” from the request instead of the request’s “target_geography_list”.

• API requests that included a "share_of_voice_list" for place-based inventory were not processing the "share_of_voice_list" correctly. This was corrected in a hot fix to production on January 13th, 2024.

v2.2.7 2024-01-09 – Change Summary

• For an /inventory/measures/summary request the max_frames attribute can be set for all frames and/or max_frames can be set on a frame by frame basis for a list of frames. When max_frames is set for all frames and also for specific frames in a frame-by-frame list, the frame-by-frame list should take precedence for the specific frame in the list over the all max_frame setting, however prior to this correction, the request global max_frame value took precedence and the frame-by-frame value was ignored.

• The endpoint /inventory/plans now recognizes a zip code based inventory_market_list.

• The response in the /inventory/named/search now formats the JSON response more cleanly when fieldset is used, e.g., superfluous “}” are no longer present in the response.

• When the list of place-based spots (all at the same location) increased in an /inventory/measures/summary request, reach_net in the response did not increase, only avg_freq increased. This has been addressed and both reach_net and avg_freq increase appropriately.

• For place-based inventory, the /inventory/plans endpoint returned aggregate reach_net and reach_pct that are significantly higher than was correct in some scenarios. This issue does not affect /inventory/measures/summary or /inventory/search/summary which both were returning correct values for all place-based queries. The incorrect reach_pct and reach_net were most affected in scenarios where the spots required to satisfy the plan goal were a very small percentage of spots that matched the plan spot selection criteria in the entire media_type_group, even then some geographies did not experience this issue depending on the exact distribution of the most average place-based spots with in the target geography.

• /inventory/plans incorrectly returned the total number of spots matching the media_type_group parameters rather than maximum allowable spots in a plan (currently 1500) when a plan goal required the maximum number of spots allowable to reach the goal.

• The error message returned when an unsupported base_segment or target_segment ids are supplied in the request has been modified to identify the root cause of the error more clearly.

• Reach_net for a very small group of roadside spots (e.g. only observed with some 2 spot groups) could return an incorrect reach_net that was higher than the sum of the reach_nets of the two spots. A check has been put in place to ensure that the reach_net for a group of spots never exceeds the sum of the reach_net of the individual spots in any spot group.

v2.2.6 2023-10-13 – Change Summary

• /inventory/search/named has been enhanced to return hourly measures.

• All spots with status published-suppressed or published-unmeasured, are now returned by /inventory/search requests without measures but with spot metadata.

• Some spots with specific internal Geopath audit statuses were incorrectly suppressing measures. This has been corrected.

• The inventory_market_list attribute now accepts zip code based geographical areas.

• All endpoints now correctly calculate pct_comp_imp_target_inmkt as imp_target_inmkt / imp_inmkt.

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

• 338 additional target audience segments were added (please see Target Audiences Available for 2023 Forecast for specific details)

• API response times have improved by 10% or more (on average) 

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

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

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

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

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

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

• Some spots return incorrect status

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

• /measures/summary/segments is not sorting correctly

• Improve fleet reach accuracy for groups with many advertising units

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

v2.2.1 2023-03-22 – Change Summary

• 214 additional target audience segments were added (please see Target Audiences Available for 2023 & 2024 Forecasts for specific details)

• Unpublished spot ids passed into inventory/measures/summary cause 500 error

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

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

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

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

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

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 User Acceptance Testing (UAT) Status 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.