An issue was corrected in /inventory/plans, where when a roadside plan query includes multiple media type groups, a reach percent goal and a single audience target geography, the calculated plan reach percent was sometimes be over-estimated (indicating a fewer number of spots satisfies the plan goal than is correct).
An issue was corrected in /inventory/plans, where multiple audience target geographies and multiple media type groups will return a 500 error if one of the media type groups returns no spots matching the media type group criteria.
An issue was corrected in /inventory/plans, where the endpoint did not default to Persons 0+ (i.e., 9330), when a target segment was omitted from the query and instead returned a 500 error.
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
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.
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.
This issue has been resolved by preventing any updated OOH asset attributes from being shown in any API endpoint until the monthly data release process and audience measurement calculations occur, at which time both the asset attributes and the corresponding audience measures become visible.
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.
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.
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.
/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.
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.
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.
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
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)
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.
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
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.
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.
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.
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.