v2.1 FAQs & Use Cases

Owned by Michael Riccio (Unlicensed)
Last updated: Feb 21, 2023 by Chris Luken
112 min read

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?

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.1/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": 12, "number_of_homes": 100, "total_number_of_homes": 1195 }, "homes": [ { "market_id": "ZIP14209", "homes_pct": 0.049829964, "dtm_calculated": "2020-04-13 09:53:02.366 -0400" }, { "market_id": "ZIP14222", "homes_pct": 0.030608576, "dtm_calculated": "2020-04-13 09:53:02.366 -0400" }, { "market_id": "ZIP14216", "homes_pct": 0.028820822, "dtm_calculated": "2020-04-13 09:53:02.366 -0400" }, { "market_id": "ZIP14215", "homes_pct": 0.027580857, "dtm_calculated": "2020-04-13 09:53:02.366 -0400" }, { "market_id": "ZIP14217", "homes_pct": 0.024441054, "dtm_calculated": "2020-04-13 09:53:02.366 -0400" }, etc... ] }

  • For a list of spots using the https://api.geopath.org/v2.1/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.1/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

  • For all 2021R1 data that is ONLY accessible via the v2.1 API, hourly impressions are available at the specific spot level for 0+(2032), 5+(8293), 18+(7166) and 21+(8228) core audiences that include group quarters populations. They are also available for 0+ (9330), 5+(2038), 18+(2035) and 21+(2036) core audiences that exclude group quarters populations.

  • 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": 256.2942, the equation would be as follows:

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

      Which equals 14416.54875

      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?

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.

Use Case: Bulk request to get inventory and measures information

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 Geopath Saved Queries to download bulk data

The Geopath API also provides a bulk file download option that provides the full inventory/search response as a single JSON file for a set of pre-determined measures. Below is a list of current files and how to retrieve them.

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 65 Billion impressions across 639K frames / 734K 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 64K frames / 75K 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.

    • 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 where the total is 779 million impressions across 3.9K frames / 3.9K spots.

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: These 3 calls are taking the same batch of 5 Bulletins and getting the Hispanic 18+ measures for a 1,2, & 4 week period in the New York CBSA with 3 minimum frequency. These are separated out because you cannot have the same inventory returned for overlapping dates in a single call.

    • Response: This is the response for the 1-week campaign, the other responses will be identical in structure with different measures depending on the time. It breaks down the measures by overall, by batch (will list multiple if there are multiple batches) and each spot in each batch individually.

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 response. Any of these can be added to the request fieldset array to limit the response to