How do I get impressions for a specific list of inventory?

The Inventory Search endpoint allows you to provide a specific list of inventory IDs to get impressions.

How do I get the Reach and Frequency for a specific list of inventory?

There are three methods depending on what you need:

• When R/F for each spot in the list is required:

  • The Inventory Search endpoint provides a measures object that includes R/F based on the “period_days” parameter used when sending the search body (default is 7 days when parameter is not provided). 

• When R/F for the whole inventory list as a single value is required:

  • The Search/Summary endpoint can be used to find aggregate measures, including R/F for the inventory list as a whole 

• When R/F is needed for the inventory list for a specific duration that is defined by specific dates:

  • The Measures/Summary endpoint takes the list of inventory by dates as a batch to determine the duration and delivers R/F for the overall list and each spot within that list.

How do I find the best market or audience for inventory?

• Zip Code or DMA:

  • Using the GET Measures/Homes endpoint for a single piece of inventory

    Using the POST Measures/Homes/Spots endpoint for a list of spots that you provide

• Audience Segment:

  • Using the Measures/Summary/Segments endpoint.

Use Case: Get the top markets for a spot or multiple spots.

As seen in the Geopath Insights Suite, it's possible to find the highest indexing market for a piece of inventory. This can help our members identify new business opportunities and can be accessed by the Geopath API. In both endpoints the markets are limited to DMA or ZIP. There are also extremely long tails of data that detail tiny percentages of audience that come from distant markets. Please keep these outliers in mind as you request data and analyze the response.

• For a Single Spot:

  • Call: This GET call is for the top zip codes for the specific spot id. The page size is limited to the top 100 on the first page.

    https://api.geopath.org/v2.2/inventory/measures/homes/30970663?reporting_level=ZIP&page_size=100

  • Response: The response includes a pagination object detailing home many markets were returned. Additional pages can be requested. The object also includes the date the market and percentage was derived, which corresponds to the most recent impression calculation date. This response has been truncated for space

    { "spot_id": 30970663, "reporting_level": "ZIP", "pagination": { "page": 1, "page_size": 100, "number_of_pages": 16, "number_of_homes": 100, "total_number_of_homes": 1586 }, "homes": [ { "market_id": "ZIP14222", "homes_pct": 0.11175677, "dtm_calculated": "2021-06-10 04:10:49.580 Z" }, { "market_id": "ZIP14209", "homes_pct": 0.09615965, "dtm_calculated": "2021-06-10 04:10:49.580 Z" }, { "market_id": "ZIP14215", "homes_pct": 0.06097116, "dtm_calculated": "2021-06-10 04:10:49.580 Z" }, { "market_id": "ZIP14216", "homes_pct": 0.056235258, "dtm_calculated": "2021-06-10 04:10:49.580 Z" }, etc... ] }

• For a list of spots using the https://api.geopath.org/v2.2/inventory/measures/homes/spots endpoint

  • Call: This POST call is for the top DMAs for a list of spots . The page size is limited to the top 100 on the first page.

    { "id_list": [ "30970663", "30970678" ], "reporting_level": "DMA" }

  • Response: The response includes each spot as an object. The data per spot is identical to the GET endpoint. The objects list all the homes for a single spot before proceeding to the next spot, so be sure to check all the pages returned to ensure all data is received.

How can I find a market ID to use in inventory searches?

• Using the Markets/Search endpoint under the Market Reference API Product.

Use Case: Finding Markets

The Market Reference product allows you to search for defined geographic areas that can be used to filter inventory or limit measures to a single or group of areas.

• There are two GET endpoints in the Market Reference product, one where you can search for markets, and one where you can get information, including spatial geometry (excluding DMA) about a specific market.

• In general Geopath currently supports 4 different market types: DMA, CBSA, County(abbreviated CNTY) and Zip Codes (ZIP).

• Using the https://api.geopath.org/v2.2/markets/search endpoint you can provide a string to search as well as set a type filter. You can use any combination of searches to find the geographic markets you need for use in the other inventory search endpoints.

  • Call: This URL is formatted with the parameters to search for zip codes that have the string 'NY'

  • Response: The response includes an ID that can be used in other API search products as well as the long format name of the market. A pagination object is also include if the response is longer than 100(max and default page size) items.

  • Call: This call just asks for markets that include the term ‘Santa' without specifying a type

  • Response: The response includes 84 markets across DMAs, CBSAs, Counties and Zip Codes that contain the word Santa

• The other GET endpoint in the Market Reference product is to get details about a specific market code.

  • Call:

  • Response: The response includes the name of the market as well as the geometry of the market. This geometry of this response has been truncated. The geometry object could be used inside a separate GeoJSON object for polygon creation in GIS systems.

How do I get hourly impressions?

Hourly Measures are represented as impressions per play and are available in the inventory/search, inventory/search/batch and /inventory/spot/{spot_id} endpoints.

To get hourly measures from the inventory/search and inventory/search/batch, provide the parameter "hourly_measures" with a true value, in the body of your search request.

To get hourly measures from /inventory/spot/{spot_id}, provide the parameter hourly_measures=true to the url of your GET request. 

• Hourly impressions are only available for the four core audiences of 0+, 5+, 18+, and 21+ at the global level and not yet available for other audiences or local markets.

Use Case: How to retrieve hourly impressions

With the launch of Geopath's new measurement system there is now an enhanced ability to see how many impressions are being generated by hour. Geopath accomplishes this by determining how many impressions happen per play of a spot within each hour of each day of the week. For static inventory, these are

• IMPORTANT: For all 2023 data that is ONLY accessible via the v2.2 API, hourly impressions are available for 0+ (9330), 5+(2038), 18+(2035) and 21+(2036) core audiences that include group quarters populations. The ability to support target audiences for 0+/5+/18+/21+ that exclude group quarters have been deprecated from the 2023 data set (and their target segment IDs have also been replaced by the target segment IDs that previously included group quarters) by design.

• They are only available for the Global market and are not yet available for local markets.

  • Call: The GET call for hourly impressions requires two parameters get passed. hourly_measures=true and target_segment, which needs to be one of the 4 supported audiences. This call is asking for the hourly measures for spot 631042 at the 0+ level.

  • Response: The response includes total_msg_impressions (aka impressions per play) for each hour of each day of the week as well as information about the spot. This response is for a static piece of inventory. This response has been edited for length.

• For digital inventory an additional step is required to understand the hourly impressions per spot.

  • Call: The call is the same, in the case the ID is for a digital spot

  • Response: The Response is also the same format. An important change is that the share_of_voice is now reflective of its digital loop at .125 sov.

  • The following equation can identify the hourly impressions for the digital spot:

  • In this case for FRI Hour 17 "17": 366.2613, the equation would be as follows:

    366.2613 * ((3600*1)/(8/.125))

    Which equals 20602.19813

    Note that the layout share of voice is found as part of the frame object.

How do I get a bulk list of inventory to use within other systems?

Many users want to be able to get a dataset to use within their own systems. This can be accomplished by using the inventory/search endpoint. There are multiple ways to accomplish this. Please see the two use cases below.

Use Case: Bulk request to get inventory and measures information from the /Search endpoint

You can request details and measures of all inventory, or a subset of inventory that matches specific criteria, using the /inventory/search endpoint. You can then request and save all pages of the results individually to use in downstream applications or processes.

Many users want to be able to get a dataset to use within their own systems. This can be accomplished by using the inventory/search endpoint.

• By Omitting many of the available search parameters, the call will return all "Published Measured" inventory available.

• Due to the fact that no segment or target market is supplied, the measures will default to 0+ Global Impressions.

• Since the max return of the search endpoint is 2000 spots, the call will have to repeated using different pages.

  • Call: This first call sets no search parameters to return all inventory. The page size is set to the maximum to increase call use efficiency

  • Response: The response includes complete inventory objects for each spot. Below, the content under "inventory_items" has been omitted for space.

  • Call: Since the first response shows 516 pages for 515,802 spots, 515 more calls are required to receive the full dataset for the 0+ Global Market impressions. The second call would be:

  • Response: The response is the same, but with a new page of data. The content under "inventory_items" has been omitted for space.

Use Case: Using a Saved Offline Search

In the v2.2 API, Geopath has introduced the ability to create a saved search that will run offline and create a downloadable file that will contain the entire search result.

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 in staging is meant only for testing and should not be used in production services or uses.

• Users will need to authenticate their credentials and provide an Authorization Header in their requests to create, list or access the saved queries.

  • Call: this call includes the Geopath Credentials for the user:

  • Response: the response includes the “access_token” that will used in the Authorization header of subsequent requests

• After authenticating, users can see the list of publicly available queries by using the GET https://api-staging.geopath.org/v2.2/inventory/search/named/list endpoint.

  • Call: this call includes the header “Authorization” with the value of “Bearer” with the previously acquired Authorization Token (note that the word Bearer and the token create a single string value). A “name” parameter can be provided to limit the result if desired. Your Geopath-API-Key is also required in the header. Here is a full cURL example of a request:

  • Response: this response includes all saved searches that are available to your user, and includes the status of the search, the url to download it, and the a version of the search body as well as a pagination object.

• Users can create a new search by using the https://api-staging.geopath.org/v2.2/inventory/search/named endpoint.

  • Call: the endpoint has the same capabilities as the regular inventory/search endpoint, but also requires an Authorization header with bearer token. It also includes additional request parameters of “name” which is required for offline processing and should be unique, as well as “offline” which indicates that the search should be conducted offline and will be downloadable once complete. All other filters in search operate as normal. So this example is creating a saved offline search of all non-digital roadside bulletins in the NY DMA.

  • Response: The response returns a download URL that can be used once the search is complete. You can use the previosuly desrcibed /search/named/list endpoint to check the status of the search as well.

• Users can also Refresh the results of a saved search if there's been a long time between access, or if the user knows new data was released that would be included in the search, by using the https://api-staging.geopath.org/v2.2/inventory/search/{search_id} endpoint.

  • Call: this call is marked for the specific saved search by using the ID in the URL. The body consists of a single parameter “refresh”. An authorized user Bearer token is required in the request headers.

  • Response: the response again includes the download url

• To download a saved search you can use the GET https://api-staging.geopath.org/v2.2/inventory/search/{search_id} endpoint.

  • You will need to provide your Geopath API key in the header of your request to the URL. The query id, which can be used within the GET /inventory/search/{search_id}, is within the URLs below after the “/datasets” portion of the URL.

  • You will need to stream and download the results of the request, as it will be too large for most programs.

    • In CURL, you can use the -O option to send the result to a specified file name. A full CURL sample:

      In Postman, you can use the "Send and Download" option to download the zip file. 

What’s the best way to get data from the Geopath API?

The /inventory/search endpoint meets most basic requirements for Geopath data needs. It’s a powerful service that can help you find inventory that best meet your needs.

How do I get summary statistics for a group of inventory?

Using the /inventory/search/summary endpoint you can request summarized measures of all inventory, or a subset of inventory that matches specific criteria.

Use Case: Search for Summary Inventory Statistics

Using the /inventory/summary/search endpoint, you can search for summary statistics across a set of inventory.

• Sample: Get a summary of all impressions.

  • Call: This call is asking for global 0+ impressions across all operators and media types.

  • Response: The response total is 70 Billion impressions across 622K frames / 760K spots

• Adding an additional search parameter into the call can change this. Sample: Search for summary of all impressions of a specific company.

  • Call: This call is asking for global 0+ impressions for a single operator across all their media types.

  • Response: The response total is 1.3 Billion impressions across 70K frames / 85K spots

• Sample: Very specific summary search.

  • Call: This call is asking for local market Hispanic Persons 25-44 impressions for two specific operators poster inventory that generate over 100,000 impressions in a specific market, and to summarize the operators seperately.

  • Response: The response includes all the same previous information about total impressions that would be there if asking for global information, but also includes the narrower market information and is broken into two objects in the “summaries” list that summarizes each operator independently.

How do I account for OOH plans of different length?

Using the /inventory/measures/summary endpoint you can find plan measures for a specific set of inventory over a period defined by specific dates.

Use Case: Obtaining measures for a set of units with different dates

• These examples use the /measures/summary endpoint to combine audience segments, markets, inventory and time to get measures

  • Call: This call is taking the same batch of 5 Bulletins and getting the Hispanic 18+ measures for a two seperate one week periods in the New York CBSA with 3 minimum frequency. Each batch must have a unique numeric ID.

  • Response: The response is broken down into mutiple objects and lists:

    • by_segment_overall: Provides the total measures for the entire period for each audience segment requested. The period in the response reflects the absolute time difference (in this case 37 days), thought the measures only account for the period run (in this case 14 days)

    • by_batch: Provides the total measures for each batch requested.

    • by_spot_overall: Provides the total measures for each spot in each batch, for the overal period that spot has run (in this case 14 days).

    • by_spot_batch: Provides the total measures for each spot in each batch for the period it runs in that batch.

How do I find inventory based on geography or audience delivery?

Using the /inventory/search endpoint you can inventory for a specific geography or rank inventory based on how well it matches a target audience.

Use Case: Finding Inventory based on geography or audience delivery

Often there are cases where the specific inventory isn't required, but it's important to find inventory that matches to the best market or target audience.

• Best Market: The inventory search endpoint is utilized to find the top spots per market. Currently, only DMA, CBSA and County level impressions are available. Inventory can be filtered to smaller markets like ZIP Code.

  • Call: This call asks for the spots sorted by the percent of in market impressions. It uses the target_geography_list to specify the county it's looking in, and then further narrows the inventory that is within a specific zip code. The measures_range_list parameter is used to limit the response to inventory that actually produces impressions in the market asked for (if this is not provided the response will include all inventory with the majority producing NULL in market impressions.)

  • Response: The response is the standard inventory search response, but sorted to the specifications in the call. This response truncates frame details for space.

• Best Audience: The inventory search endpoint is utilized to find the top spots for a specific audience segment. This search can be can limited to a specific list of inventory, or inventory owned by specific company etc.... Inventory can also be filtered by a minimum number of target impressions to limit the response.

  • Call: This call asks for the spots sorted by the index of the target impressions. It uses the inventory_market_list to specify the DMA when inventory is located. The measures_range_list parameter is used to limit the response to inventory that produces over 1000 impressions of the audience asked for (if this is not provided the response will include all inventory with some producing very low impressions for the audience.)

  • Response: The response is the standard inventory search response, but sorted to the specifications in the call. This response truncates frame details for space.

How do I find audience segment ids?

You can use any of endpoints in the segment reference api product.

How can I ask Geopath questions about the API?

The best way to contact Geopath about the API is to email apisupport@geopath.org.

How can I limit the fields returned in the search results?

• The results of a search through the /inventory/search endpoint can be overwhelming and provide a lot of data that is not needed.

• To limit the data that is included in the response, you can provide a request parameter called "fieldset".

• This parameter accepts an array of strings which are the keys from the response body. For example, if you wanted to only return the frame id in the response, in the fieldset you would add "frame_id". If you wanted to include a key that was in a sub-object like the latitude, which is included in the location object, you would need to provide the path via dot notation. For this example, in the fieldset you would provide "location.latitude".

• Below is a full list of all the keys provided in the default nested response. Any of these can be added to the request fieldset array to limit the response to the fields provided.