Use Case: Get all the spot ids for a specific operator.
Step 1: use the inventory/spot/id/search endpoint to get all the spot_ids for a specific operator.
Call:
To get an accurate count of inventory include a minimum of 0 impressions in the measures_range_list
{
"operator_name_list": [
"Intersection"
],
"measures_range_list": [
{
"type": "imp",
"min": 0
}
],
"page_size": 50001
}
Response:
As you can see the response includes a count of total inventory, and a pagination object. For this call there are 2 pages since the page size is capped at 50,000 spot results. A second call is needed to get the remainder of the spot_ids
{
"inventory_summary": {
"inventory_count": 26602,
"pagination": {
"page": 1,
"page_size": 50001,
"number_of_pages": 2,
"number_of_frames": 29960,
"number_of_spots": 53359
},
"frame_list": [
{
"frame_id": 50187935,
"spot_id_list": [
50190589
]
},
{
"frame_id": 30819503,
"spot_id_list": [
30819637,
30819639,
30819640,
30819638,
30819503,
30819636
]
},
...etc
Call:
This call is the same as the first one, but adds a page key/value to only get the second page of results.
{
"operator_name_list": [
"Intersection"
],
"measures_range_list": [
{
"type": "imp",
"min": 0
}
],
"page": 2,
"page_size": 50001
}
Result:
The second page result is the same as the first one, but for a smaller inventory count as this is the second and final page. The pagination object still included the overall count for the search.
{
"inventory_summary": {
"inventory_count": 3358,
"pagination": {
"page": 2,
"page_size": 50001,
"number_of_pages": 2,
"number_of_frames": 29960,
"number_of_spots": 53359
},
"frame_list": [
{
"frame_id": 30542309,
"spot_id_list": [
30542309
]
},
etc...
When creating a plan sometimes a user will want to lock a certain parameter like number of a media type or TRPs.
This can be accomplished in the https://api.geopath.org/v2.1/inventory/plans endpoint and using the lock object to set what you want locked. The lock object can be provided within different objects depending on the lock requirements. A Goal object is always required when using the endpoint, but can be set at 0 for a measure.
Call:
This call locks the total number of Bulletin inventory in a specific market with a TRP goal of 100 over 1 week. Note that locking the number of inventory might make the request fail to reach a set goal.
{
"target_geography_list": [
"DMA623"
],
"target_segment": 2032,
"media_type_group_list": [
{
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50,
"max": 1000
},
{
"type": "imp_target",
"min": 0
}
],
"media_type_list": [
"Bulletin"
],
"lock": {
"measure": "spots",
"value": 25
}
}
],
"allocation_method": "equal",
"goal": {
"period_days": 7,
"measure": "trp",
"value": 100
}
}
Response:
The response shows that the number of inventory was locked at 25 spots and failed to meet the goal of 100 TRPs.
{
"allocation_list": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA623",
"market": "DMA623",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.446190288,
"imp_target_inmkt": 7043622.180732,
"imp_target": 8212218.20723589,
"imp_inmkt": 7043622.180732,
"imp": 8212218.20723589,
"pct_imp_inmkt": 0.8577003196,
"pct_imp_target_inmkt": 0.8577003196,
"pop_inmkt": 8191034,
"pop_target_inmkt": 8191034,
"reach_pct": 35.153379787,
"reach_net": 2879425,
"trp": 85.991856226,
"eff_freq_min": 3,
"eff_freq_avg": 5.345805722,
"eff_reach_net": 1317598,
"eff_reach_pct": 16.085855097,
"spots": 25
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": null,
"operator_name_list": null,
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 25.0
}
}
}
],
"summaries": {
"by_media_type_group": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA623",
"market": "DMA623",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.446190288,
"imp_target_inmkt": 7043622.180732,
"imp_target": 8212218.20723589,
"imp_inmkt": 7043622.180732,
"imp": 8212218.20723589,
"pct_imp_inmkt": 0.8577003196,
"pct_imp_target_inmkt": 0.8577003196,
"pop_inmkt": 8191034,
"pop_target_inmkt": 8191034,
"reach_pct": 35.153379787,
"reach_net": 2879425,
"trp": 85.991856226,
"eff_freq_min": 3,
"eff_freq_avg": 5.345805722,
"eff_reach_net": 1317598,
"eff_reach_pct": 16.085855097,
"spots": 25
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": null,
"operator_name_list": null,
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 25.0
}
}
}
],
"by_operator": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA623",
"market": "DMA623",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.446190288,
"imp_target_inmkt": 7043622.180732,
"imp_target": 8212218.20723589,
"imp_inmkt": 7043622.180732,
"imp": 8212218.20723589,
"pct_imp_inmkt": 0.8577003196,
"pct_imp_target_inmkt": 0.8577003196,
"pop_inmkt": 8191034,
"pop_target_inmkt": 8191034,
"reach_pct": 35.153379787,
"reach_net": 2879425,
"trp": 85.991856226,
"eff_freq_min": 3,
"eff_freq_avg": 5.345805722,
"eff_reach_net": 1317598,
"eff_reach_pct": 16.085855097,
"spots": 25
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": null,
"operator_name_list": null,
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 25.0
}
}
}
],
"total": {
"measures": {
"measures_type": "plan_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA623",
"market": "DMA623",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.446190288,
"imp_target_inmkt": 7043622.180732,
"imp_target": 8212218.20723589,
"imp_inmkt": 7043622.180732,
"imp": 8212218.20723589,
"pct_imp_inmkt": 0.8577003196,
"pct_imp_target_inmkt": 0.8577003196,
"pop_inmkt": 8191034,
"pop_target_inmkt": 8191034,
"reach_pct": 35.153379787,
"reach_net": 2879425,
"trp": 85.991856226,
"eff_freq_min": 3,
"eff_freq_avg": 5.345805722,
"eff_reach_net": 1317598,
"eff_reach_pct": 16.085855097,
"spots": 25
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": null,
"operator_name_list": null,
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 25.0
}
}
}
}
}
Call:
This call is locking the amount of inventory for a specific operators bulletins, while maintaining no lock on specific operators posters. Note that there are two lock objects set within the objects in the media_type_group_list.
{
"target_geography_list": [
"DMA501"
],
"target_segment": 2032,
"media_type_group_list": [
{
"operator_name_list": [
"Lamar"
],
"frame_media_name_list": [],
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50,
"max": 1000
},
{
"type": "imp_target",
"min": 0
}
],
"media_type_list": [
"Bulletin"
],
"lock": {
"measure": "spots",
"value": 15
}
},
{
"operator_name_list": [
"Lamar"
],
"frame_media_name_list": [],
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50,
"max": 1000
},
{
"type": "imp_target",
"min": 0
}
],
"media_type_list": [
"Poster"
]
},
{
"operator_name_list": [
"OUTFRONT"
],
"frame_media_name_list": [],
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50,
"max": 1000
},
{
"type": "imp_target",
"min": 0
}
],
"media_type_list": [
"Bulletin"
],
"lock": {
"measure": "spots",
"value": 15
}
},
{
"operator_name_list": [
"OUTFRONT"
],
"frame_media_name_list": [],
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50,
"max": 1000
},
{
"type": "imp_target",
"min": 0
}
],
"media_type_list": [
"Poster"
]
}
],
"allocation_method": "equal",
"goal": {
"period_days": 14,
"measure": "trp",
"value": 150
}
}
Response:
The response shows the plan results in different as a total and by different aggregations. Note that locking the bulletins at 15 per operator failed to meet the TRP goal.
{
"allocation_list": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 4.207746887,
"imp_target_inmkt": 1.23022167475307E7,
"imp_target": 1.31125700218437E7,
"imp_inmkt": 1.23022167475307E7,
"imp": 1.31125700218437E7,
"pct_imp_inmkt": 0.938200271,
"pct_imp_target_inmkt": 0.938200271,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 13.446181262,
"reach_net": 2923706,
"trp": 56.57812734,
"eff_freq_min": 3,
"eff_freq_avg": 5.561019674,
"eff_reach_net": 2212223,
"eff_reach_pct": 10.174056316,
"spots": 15
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
},
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.67614061,
"imp_target_inmkt": 1.64563402749068E7,
"imp_target": 1.74169879830018E7,
"imp_inmkt": 1.64563402749068E7,
"imp": 1.74169879830018E7,
"pct_imp_inmkt": 0.9448442114,
"pct_imp_target_inmkt": 0.9448442114,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 13.333535082,
"reach_net": 2899213,
"trp": 75.683019957,
"eff_freq_min": 3,
"eff_freq_avg": 6.334258187,
"eff_reach_net": 2597990,
"eff_reach_pct": 11.948205729,
"spots": 83
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": null
}
},
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.156854934,
"imp_target_inmkt": 1.63376556638252E7,
"imp_target": 1.67651655615922E7,
"imp_inmkt": 1.63376556638252E7,
"imp": 1.67651655615922E7,
"pct_imp_inmkt": 0.9745001088,
"pct_imp_target_inmkt": 0.9745001088,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 14.570351145,
"reach_net": 3168143,
"trp": 75.137187188,
"eff_freq_min": 3,
"eff_freq_avg": 6.023909691,
"eff_reach_net": 2712135,
"eff_reach_pct": 12.473159632,
"spots": 15
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": [],
"operator_name_list": [
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
},
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 4.654720242,
"imp_target_inmkt": 1.64568738673595E7,
"imp_target": 1.71416949283274E7,
"imp_inmkt": 1.64568738673595E7,
"imp": 1.71416949283274E7,
"pct_imp_inmkt": 0.9600493963,
"pct_imp_target_inmkt": 0.9600493963,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 16.259940452,
"reach_net": 3535524,
"trp": 75.685473959,
"eff_freq_min": 3,
"eff_freq_avg": 5.795824231,
"eff_reach_net": 2839436,
"eff_reach_pct": 13.058621336,
"spots": 73
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": null
}
}
],
"summaries": {
"by_media_type_group": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.519270977179628,
"imp_target_inmkt": 3.29132141422663E7,
"imp_target": 3.4558682911329195E7,
"imp_inmkt": 3.29132141422663E7,
"imp": 3.4558682911329195E7,
"pct_imp_inmkt": 0.9523862418806629,
"pct_imp_target_inmkt": 0.9523862418806629,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 27.425450669520266,
"reach_net": 5963326,
"trp": 151.3684939163548,
"eff_freq_min": 3,
"eff_freq_avg": 6.455894551256478,
"eff_reach_net": 5098165,
"eff_reach_pct": 23.446556122403628,
"spots": 156
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar",
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": null
}
},
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.054818704234596,
"imp_target_inmkt": 2.86398724113559E7,
"imp_target": 2.98777355834359E7,
"imp_inmkt": 2.86398724113559E7,
"imp": 2.98777355834359E7,
"pct_imp_inmkt": 0.9585690432053269,
"pct_imp_target_inmkt": 0.9585690432053269,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 26.057376581533408,
"reach_net": 5665856,
"trp": 131.7153145276196,
"eff_freq_min": 3,
"eff_freq_avg": 6.161200579004361,
"eff_reach_net": 4648424,
"eff_reach_pct": 21.378189662655743,
"spots": 30
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar",
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
}
],
"by_operator": [
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.293226943108967,
"imp_target_inmkt": 2.8758557022437498E7,
"imp_target": 3.05295580048455E7,
"imp_inmkt": 2.8758557022437498E7,
"imp": 3.05295580048455E7,
"pct_imp_inmkt": 0.9419906117826233,
"pct_imp_target_inmkt": 0.9419906117826233,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 24.986865048241924,
"reach_net": 5433086,
"trp": 132.26114729718188,
"eff_freq_min": 3,
"eff_freq_avg": 6.326273208772847,
"eff_reach_net": 4545892,
"eff_reach_pct": 20.90664486538,
"spots": 98
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin",
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
},
{
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 5.2992448272892,
"imp_target_inmkt": 3.2794529531184703E7,
"imp_target": 3.39068604899196E7,
"imp_inmkt": 3.2794529531184703E7,
"imp": 3.39068604899196E7,
"pct_imp_inmkt": 0.9671945163113644,
"pct_imp_target_inmkt": 0.9671945163113644,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 28.461161177175697,
"reach_net": 6188529,
"trp": 150.8226611467925,
"eff_freq_min": 3,
"eff_freq_avg": 6.309790585791979,
"eff_reach_net": 5197404,
"eff_reach_pct": 23.9029582830223,
"spots": 88
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin",
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
}
],
"total": {
"measures": {
"measures_type": "plan_measures",
"period_days": 14,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "DMA501",
"market": "DMA501",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 6.109308331632881,
"imp_target_inmkt": 6.15530865536222E7,
"imp_target": 6.44364184947651E7,
"imp_inmkt": 6.15530865536222E7,
"imp": 6.44364184947651E7,
"pct_imp_inmkt": 0.9552530694831037,
"pct_imp_target_inmkt": 0.9552530694831037,
"pop_inmkt": 21743768,
"pop_target_inmkt": 21743768,
"reach_pct": 46.33647429091411,
"reach_net": 10075295,
"trp": 283.08380844397436,
"eff_freq_min": 3,
"eff_freq_avg": 7.110461666127006,
"eff_reach_net": 8656693,
"eff_reach_pct": 39.8122965478509,
"spots": 186
},
"media_type_group": {
"classification_type_list": null,
"construction_type_list": null,
"media_type_list": [
"Bulletin",
"Poster"
],
"frame_media_name_list": [],
"operator_name_list": [
"Lamar",
"OUTFRONT"
],
"include_spot_list": null,
"exclude_spot_list": null,
"digital": null,
"rotating": null,
"measures_range_list": [
{
"type": "index_comp_target",
"min": 50.0,
"max": 1000.0
},
{
"type": "imp_target",
"min": 0.0,
"max": null
}
],
"lock": {
"measure": "spots",
"value": 15.0
}
}
}
}
}
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: Search for summary of all impressions
Call:
This call is asking for global 0+ impressions across all operators and media types.
{
"base_segment": 2032,
"target_segment": 2032,
"sort": {
"measure": "pct_comp_imp_target",
"type": "desc"
},
"measures_range_list": [
{
"type": "imp",
"min": 0
}
]
}
Response:
The response total is 65 Billion impressions across 639K frames / 734K spots
{
"summary_level_list": [
"Universe"
],
"summaries": [
{
"measures_type": "aggregate_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 198.64833991,
"imp_target_inmkt": 6.54022196020442E10,
"imp_target": 6.54022196020442E10,
"imp_inmkt": 6.54022196020442E10,
"imp": 6.54022196020442E10,
"pct_imp_inmkt": 1.0,
"pct_imp_target_inmkt": 1.0,
"pop_inmkt": 329236175,
"pop_target_inmkt": 329236175,
"reach_pct": 100.0,
"reach_net": 329236175,
"trp": 19864.833990993,
"eff_freq_min": 3,
"eff_freq_avg": 198.64833991,
"eff_reach_net": 329236175,
"eff_reach_pct": 100.0,
"summarizes": {
"type": "Universe",
"summarizes_id_list": null,
"id": null,
"name": null,
"geometry": null
},
"frames": 639946,
"spots": 734804
}
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_summaries": 1
}
}
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.
{
"base_segment": 2032,
"target_segment": 2032,
"operator_name_list": [
"OUTFRONT"
],
"sort": {
"measure": "pct_comp_imp_target",
"type": "desc"
},
"measures_range_list": [
{
"type": "imp",
"min": 0
}
]
}
Response:
The response total is 1.3 Billion impressions across 64K frames / 75K spots
{
"summary_level_list": [
"Universe"
],
"summaries": [
{
"measures_type": "aggregate_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 39.507893961,
"imp_target_inmkt": 1.30074249248078E10,
"imp_target": 1.30074249248078E10,
"imp_inmkt": 1.30074249248078E10,
"imp": 1.30074249248078E10,
"pct_imp_inmkt": 1.0,
"pct_imp_target_inmkt": 1.0,
"pop_inmkt": 329236175,
"pop_target_inmkt": 329236175,
"reach_pct": 99.999977203,
"reach_net": 329236100,
"trp": 3950.788495465,
"eff_freq_min": 3,
"eff_freq_avg": 39.524948379,
"eff_reach_net": 329094040,
"eff_reach_pct": 99.956828723,
"summarizes": {
"type": "Universe",
"summarizes_id_list": null,
"id": null,
"name": null,
"geometry": null
},
"frames": 64619,
"spots": 75004
}
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_summaries": 1
}
}
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.
{
"base_segment": 2032,
"target_segment": 7619,
"target_geography_list": [
"DMA803"
],
"inventory_market_list": [
"DMA803"
],
"operator_name_list": [
"OUTFRONT",
"Clear Channel"
],
"media_type_list": [
"Poster"
],
"measures_range_list": [
{
"type": "imp",
"min": 100000
}
]
}
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
{
"summary_level_list": [
"Universe"
],
"summaries": [
{
"measures_type": "aggregate_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "7619",
"target_geo": "DMA803",
"market": "DMA803",
"index_comp_target": 121.079337699,
"pct_comp_pop_target_inmkt": 0.106013,
"pct_comp_imp_target": 0.1266190738,
"pct_comp_imp_target_inmkt": 0.1283598383,
"freq_avg": 49.232208946,
"imp_target_inmkt": 9.71006195374118E7,
"imp_target": 9.86522281540164E7,
"imp_inmkt": 7.56471968508678E8,
"imp": 7.79126123679314E8,
"pct_imp_inmkt": 0.9709236355,
"pct_imp_target_inmkt": 0.9842719354,
"pop_inmkt": 18604423,
"pop_target_inmkt": 1972303,
"reach_pct": 99.999779752,
"reach_net": 1972299,
"trp": 4923.210051266,
"eff_freq_min": 3,
"eff_freq_avg": 49.237457196,
"eff_reach_net": 1972088,
"eff_reach_pct": 99.989120716,
"summarizes": {
"type": "Universe",
"summarizes_id_list": null,
"id": null,
"name": null,
"geometry": null
},
"frames": 3934,
"spots": 3952
}
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_summaries": 1
}
}
As seen in the Geopath Insights Suite, it's possible to find the highest indexing segment for a piece of inventory. This can help our members identify new business opportunities and can be accessed by the Geopath API.
Using the https://api.geopath.org/v2.1/inventory/measures/summary/segments endpoint its possible to search for a single id or list of multiple ids. If no inventory details are provided, the endpoint will generate the summary based on all inventory that match the search parameters. The available search parameters are the same as in the inventory search endpoint. If specific segments are not provided, the endpoint defaults to the list of Claritas PRIZM Segments.
######Call: This call specifies just a single spot id and a sort order. Since no specific segments are listed to rank, it will rank the PRIZM segments.
{
"id_list": [
"30970663"
],
"sort": {
"measure": "index_comp_target",
"type": "DESC"
}
}
######Response: The response first details the segment ids that are included, and then breaks down the summary statistics for each segment for the inventory that matches the search parameters in the call.
{
"segment_list": [
"1956",
"1943",
"1932",
"1930",
"1934",
"1938",
"1916",
"1911",
"1903",
"1918",
"1942",
"1924",
"1928",
"1919",
"1908",
"1913",
"1920",
"1952",
"1960",
"1959",
"1910",
"1950",
"1921",
"1896",
"1958",
"1905",
"1907",
"1931",
"1939",
"1915",
"1906",
"1899",
"1941",
"1894",
"1957",
"1904",
"1936",
"1944",
"1929",
"1909",
"1933",
"1955",
"1900",
"1922",
"1949",
"1945",
"1902",
"1901",
"1925",
"1953",
"1937",
"1912",
"1926",
"1917",
"1951",
"1954",
"1897",
"1927",
"1948",
"1895",
"1898",
"1893",
"1923",
"1914",
"1935",
"1947",
"1940",
"1946"
],
"segment_summaries": [
{
"measures_type": "segment_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "1956",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 1873.743977531,
"pct_comp_pop_target_inmkt": 0.004271,
"pct_comp_imp_target": 0.08002760528,
"pct_comp_imp_target_inmkt": 0.08002760528,
"freq_avg": 6.152557087,
"imp_target_inmkt": 57648.853075908,
"imp_target": 57648.853075908,
"imp_inmkt": 720362.09098032,
"imp": 720362.09098032,
"pct_imp_inmkt": 1,
"pct_imp_target_inmkt": 1,
"pop_inmkt": 329236175,
"pop_target_inmkt": 1406202,
"reach_pct": 0.6663268414,
"reach_net": 9370,
"trp": 4.09961393,
"eff_freq_min": 3,
"eff_freq_avg": 8.100622399,
"eff_reach_net": 7117,
"eff_reach_pct": 0.5060862892,
"segment": {
"id": 1956,
"id_ads": null,
"id_v1": null,
"available_search": true,
"available_calc": false,
"name": "40 Aspiring A-Listers",
"description": "40 Aspiring A-Listers",
"source_id": 1,
"source_name": "Claritas",
"version": "2018",
"category_id": 2,
"category_name": "PRIZMPremier",
"subcategory_id": 20,
"subcategory_name": "Young Achievers"
},
"frames": 1,
"spots": 6
},
{
"measures_type": "segment_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "1943",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 1285.2460011,
"pct_comp_pop_target_inmkt": 0.007927,
"pct_comp_imp_target": 0.1018814505,
"pct_comp_imp_target_inmkt": 0.1018814505,
"freq_avg": 5.79632373,
"imp_target_inmkt": 73391.534719476,
"imp_target": 73391.534719476,
"imp_inmkt": 720362.09098032,
"imp": 720362.09098032,
"pct_imp_inmkt": 1,
"pct_imp_target_inmkt": 1,
"pop_inmkt": 329236175,
"pop_target_inmkt": 2609768,
"reach_pct": 0.4851672024,
"reach_net": 12662,
"trp": 2.812186168,
"eff_freq_min": 3,
"eff_freq_avg": 7.550617428,
"eff_reach_net": 9720,
"eff_reach_pct": 0.3724445312,
"segment": {
"id": 1943,
"id_ads": null,
"id_v1": null,
"available_search": true,
"available_calc": false,
"name": "45 Urban Modern Mix",
"description": "45 Urban Modern Mix",
"source_id": 1,
"source_name": "Claritas",
"version": "2018",
"category_id": 2,
"category_name": "PRIZMPremier",
"subcategory_id": 17,
"subcategory_name": "Sustaining Families"
},
"frames": 1,
"spots": 6
},
{
"measures_type": "segment_measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "1932",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 725.727706332,
"pct_comp_pop_target_inmkt": 0.005867,
"pct_comp_imp_target": 0.04257844453,
"pct_comp_imp_target_inmkt": 0.04257844453,
"freq_avg": 5.581246388,
"imp_target_inmkt": 30671.897332686,
"imp_target": 30671.897332686,
"imp_inmkt": 720362.09098032,
"imp": 720362.09098032,
"pct_imp_inmkt": 1,
"pct_imp_target_inmkt": 1,
"pop_inmkt": 329236175,
"pop_target_inmkt": 1931771,
"reach_pct": 0.2844813528,
"reach_net": 5496,
"trp": 1.587760523,
"eff_freq_min": 3,
"eff_freq_avg": 7.468115648,
"eff_reach_net": 4107,
"eff_reach_pct": 0.2126052405,
"segment": {
"id": 1932,
"id_ads": null,
"id_v1": null,
"available_search": true,
"available_calc": false,
"name": "31 Connected Bohemians",
"description": "31 Connected Bohemians",
"source_id": 1,
"source_name": "Claritas",
"version": "2018",
"category_id": 2,
"category_name": "PRIZMPremier",
"subcategory_id": 15,
"subcategory_name": "Midlife Success"
},
"frames": 1,
"spots": 6
},
etc...
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_summaries": 68
}
}
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.
Call:
This url is formatted with the parameters to search for zip codes that have the string 'NY'
https://api.geopath.org/v2.1/markets/search?type=Zip Codes&q=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.
{
"markets": [
{
"id": "ZIP14716",
"name": "14716 - Brocton, NY",
"type": "Zip Codes"
},
{
"id": "ZIP10567",
"name": "10567 - Cortlandt Manor, NY",
"type": "Zip Codes"
},
{
"id": "ZIP11225",
"name": "11225 - Brooklyn, NY",
"type": "Zip Codes"
},
{
"id": "ZIP12827",
"name": "12827 - Fort Ann, NY",
"type": "Zip Codes"
},
{
"id": "ZIP12546",
"name": "12546 - Millerton, NY",
"type": "Zip Codes"
},
{
"id": "ZIP14150",
"name": "14150 - Tonawanda, NY",
"type": "Zip Codes"
},
etc...
],
"pagination": {
"page": 1,
"page_size": 100,
"number_of_pages": 19,
"next_page": "{{api.basepath}}/v2.1/markets/search?q=NY&type=Zip+Codes&page=2&pageSize=100"
}
}
Call:
This call just asks for markets that include the term 'Santa' without specifying a type
https://api.geopath.org/v2.1/markets/search?q=Santa
Response:
The response includes 84 markets across DMAs, CBSAs, Counties and Zip Codes that contain the word Santa
{
"markets": [
{
"id": "CNTY06083",
"name": "Santa Barbara County, CA",
"type": "County"
},
{
"id": "DMA790",
"name": "Albuquerque-Santa Fe, NM",
"type": "DMA"
},
{
"id": "ZIP84655",
"name": "84655 - Santaquin, UT",
"type": "Zip Codes"
},
{
"id": "ZIP95065",
"name": "95065 - Santa Cruz, CA",
"type": "Zip Codes"
},
{
"id": "ZIP87505",
"name": "87505 - Santa Fe, NM",
"type": "Zip Codes"
},
{
"id": "ZIP77517",
"name": "77517 - Santa Fe, TX",
"type": "Zip Codes"
},
{
"id": "ZIP77510",
"name": "77510 - Santa Fe, TX",
"type": "Zip Codes"
},
{
"id": "ZIP88008",
"name": "88008 - Santa Teresa, NM",
"type": "Zip Codes"
},
{
"id": "ZIP93111",
"name": "93111 - Santa Barbara, CA",
"type": "Zip Codes"
},
{
"id": "CBSA04218",
"name": "Santa Isabel, PR",
"type": "CBSA"
},
{
"id": "CBSA42100",
"name": "Santa Cruz-Watsonville, CA Metropolitan Statistical Area",
"type": "CBSA"
},
etc...
],
"pagination": {
"page": 1,
"page_size": 100,
"number_of_pages": 1,
"next_page": null
}
}
You can use any combination of searches to find the geographic markets you need for use in the other inventory search endpoints. The other GET endpoint in the Market Reference product is to get details about a specific market code.
Call:
https://api.geopath.org/v2.1/markets/ZIP92091
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 seperate GeoJSON object for polygon creation in GIS systems.
{
"_id": null,
"market": {
"id": "ZIP92091",
"name": "92091 - Rancho Santa Fe, CA",
"type": "Zip Codes",
"location": null,
"createdAt": "2017-09-21 18:23:45.676872",
"updatedAt": "2017-09-21 18:23:45.676872",
"sourceMarketID": "92091",
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-117.18712400017245,
33.05275399989722
],
[
-117.18710600024167,
33.05281800015064
],
[
-117.18710100001113,
33.05283800017361
],
[
-117.18706700024181,
33.052909999896656
],
[
-117.18695999980413,
33.05307899959621
],
etc...
]
]
]
},
"userID": null,
"companyID": null
}
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.)
{
"target_geography_list": [
"CNTY34023"
],
"inventory_market_list": [
"ZIP08904"
],
"sort": {
"measure": "pct_imp_target_inmkt",
"type": "DESC"
},
"measures_range_list": [
{
"type": "imp_inmkt",
"min": 1
}
],
"page": 1,
"page_size": 1000
}
Response:
The response is the standard inventory search response, but sorted to the specifications in the call. This response truncates frame details for space.
{
"inventory_summary": {
"inventory_count": 5,
"invalid_ids": null,
"filtered_invalid_ids": null,
"inventory_items": [
{
"frame_id": 631041,
etc...
"spot_references": [
{
"spot_id": 631041,
"uri": "{{api.basepath}}/v2.1/inventory/spot/631041",
"length": null,
"spot_rotating": false,
"created_dtm": "2005-09-03T00:00:00.000Z",
"updated_dtm": "2011-10-11T13:07:00.000Z",
"measures": {
"measures_type": "Measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CNTY34023",
"market": "CNTY34023",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.604300908,
"imp_target_inmkt": 52261.396395154,
"imp_target": 91957.562656792,
"imp_inmkt": 52261.396395154,
"imp": 91957.562656792,
"pct_imp_inmkt": 0.5683208089,
"pct_imp_target_inmkt": 0.5683208089,
"pop_inmkt": 847763,
"pop_target_inmkt": 847763,
"reach_pct": 1.710352041,
"reach_net": 14500,
"trp": 6.164623414,
"eff_freq_min": 3,
"eff_freq_avg": 4.983678342,
"eff_reach_net": 10487,
"eff_reach_pct": 1.236962539
}
}
]
},
{
"frame_id": 631043,
etc...
"measures": {
"measures_type": "Measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CNTY34023",
"market": "CNTY34023",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.518249282,
"imp_target_inmkt": 20004.071179104,
"imp_target": 36186.786566725,
"imp_inmkt": 20004.071179104,
"imp": 36186.786566725,
"pct_imp_inmkt": 0.5528004301,
"pct_imp_target_inmkt": 0.5528004301,
"pop_inmkt": 847763,
"pop_target_inmkt": 847763,
"reach_pct": 0.9370121326,
"reach_net": 7944,
"trp": 2.35963013,
"eff_freq_min": 3,
"eff_freq_avg": 5.421216439,
"eff_reach_net": 3690,
"eff_reach_pct": 0.4352584252
}
},
{
"frame_id": 631044,
etc...
"measures": {
"measures_type": "Measures",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CNTY34023",
"market": "CNTY34023",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.841447479,
"imp_target_inmkt": 32605.566498443,
"imp_target": 59189.998261472,
"imp_inmkt": 32605.566498443,
"imp": 59189.998261472,
"pct_imp_inmkt": 0.5508627717,
"pct_imp_target_inmkt": 0.5508627717,
"pop_inmkt": 847763,
"pop_target_inmkt": 847763,
"reach_pct": 1.001203576,
"reach_net": 8488,
"trp": 3.846070954,
"eff_freq_min": 3,
"eff_freq_avg": 5.029528405,
"eff_reach_net": 6483,
"eff_reach_pct": 0.7646981275
}
}
etc...
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_frames": 5,
"number_of_spots": 5
}
}
}
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.)
{
"base_segment": 9072,
"target_segment": 5559,
"inventory_market_list": [
"DMA501"
],
"sort": {
"measure": "index_comp_target",
"type": "DESC"
},
"measures_range_list": [
{
"type": "imp_target",
"min": 1000
}
],
"page": 1,
"page_size": 1000
}
Response:
The response is the standard inventory search response, but sorted to the specifications in the call. This response truncates frame details for space.
{
"inventory_summary": {
"inventory_count": 1000,
"invalid_ids": null,
"filtered_invalid_ids": null,
"inventory_items": [
{
"frame_id": 30952194,
etc...,
"measures": {
"measures_type": "Measures",
"period_days": 7,
"base_segment": "9072",
"target_segment": "2032",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 440.755178074,
"pct_comp_pop_target_inmkt": 20.661281,
"pct_comp_imp_target": 91.065665864,
"pct_comp_imp_target_inmkt": 91.065665864,
"freq_avg": 3.294405237,
"imp_target_inmkt": 45716.188531433,
"imp_target": 45716.188531433,
"imp_inmkt": 502.013443791,
"imp": 502.013443791,
"pct_imp_inmkt": 1.0,
"pct_imp_target_inmkt": 1.0,
"pop_inmkt": 15934935,
"pop_target_inmkt": 329236175,
"reach_pct": 0.004214882265,
"reach_net": 13877,
"trp": 0.01388553021,
"eff_freq_min": 3,
"eff_freq_avg": 5.163654901,
"eff_reach_net": 8853,
"eff_reach_pct": 0.002689089506
}
},
{
"frame_id": 30951776,
etc...
"measures": {
"measures_type": "Measures",
"period_days": 7,
"base_segment": "9072",
"target_segment": "2032",
"target_geo": "Defaulted to GLOBAL",
"market": "Defaulted to GLOBAL",
"index_comp_target": 440.755178074,
"pct_comp_pop_target_inmkt": 20.661281,
"pct_comp_imp_target": 91.065665864,
"pct_comp_imp_target_inmkt": 91.065665864,
"freq_avg": 3.294405237,
"imp_target_inmkt": 45716.188531433,
"imp_target": 45716.188531433,
"imp_inmkt": 502.013443791,
"imp": 502.013443791,
"pct_imp_inmkt": 1.0,
"pct_imp_target_inmkt": 1.0,
"pop_inmkt": 15934935,
"pop_target_inmkt": 329236175,
"reach_pct": 0.004214882265,
"reach_net": 13877,
"trp": 0.01388553021,
"eff_freq_min": 3,
"eff_freq_avg": 5.163654901,
"eff_reach_net": 8853,
"eff_reach_pct": 0.002689089506
}
},
etc...
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 68,
"number_of_frames": 42644,
"number_of_spots": 67943
}
}
}
The Segment Reference Product allows you to search the thousands of audiences Geopath offers that can be used in the other inventory search endpoints.
There are currently 3 endpoints within the Segment Reference Endpoint. A GET endpoint to search the entire catalog, A POST endpoint to provide a list of segment IDs and get information about them, and a GET endpoint to get information about a single segment ID.
A Good way to start understanding the hierarchy in a functional way and to break down sources, categories and subcategories is to ask the call to return without the segments.
Call:
This call sets the exclude_segments parameter to true, to display only the sources, categories and subcategories.
https://api.geopath.org/v2.1/segments/catalog?exclude_segments=true
Response:
This response exlcudes the details of each segment, showing instead the overview of the audiences available with their ids. This response has been truncated for length
{
"sources": [
{
"id": 1,
"name": "Claritas",
"version": "2018",
"description": "Claritas segments",
"categories": [
{
"id": 2,
"name": "PRIZMPremier",
"description": "PRIZMPremier",
"subcategories": [
{
"id": 14,
"name": "Mainstream Families",
"description": "Mainstream Families",
"segments": null
},
{
"id": 11,
"name": "Affluent Empty Nests",
"description": "Affluent Empty Nests",
"segments": null
},
{
"id": 12,
"name": "Cautious Couples",
"description": "Cautious Couples",
"segments": null
},
{
"id": 20,
"name": "Young Achievers",
"description": "Young Achievers",
"segments": null
},
{
"id": 17,
"name": "Sustaining Families",
"description": "Sustaining Families",
"segments": null
},
{
"id": 15,
"name": "Midlife Success",
"description": "Midlife Success",
"segments": null
},
{
"id": 10,
"name": "Accumulated Wealth",
"description": "Accumulated Wealth",
"segments": null
},
{
"id": 19,
"name": "Young Accumulators",
"description": "Young Accumulators",
"segments": null
},
{
"id": 16,
"name": "Striving Singles",
"description": "Striving Singles",
"segments": null
},
{
"id": 13,
"name": "Conservative Classics",
"description": "Conservative Classics",
"segments": null
},
{
"id": 18,
"name": "Sustaining Seniors",
"description": "Sustaining Seniors",
"segments": null
}
]
},
{
"id": 1,
"name": "ConsumerProfiles",
"description": "ConsumerProfiles",
"subcategories": [
{
"id": 34,
"name": "MRI Home Improvements",
"description": "MRI Home Improvements",
"segments": null
},
{
"id": 28,
"name": "Food and Beverages",
"description": "Food and Beverages",
"segments": null
},
{
"id": 6,
"name": "Radio",
"description": "Radio",
"segments": null
},
etc...
The catalog search endpoint has many possible parameters to filter down possible results. This document provides an overview of the hierarchy of audience segments.
Call:
This call provides all endpoints that include the term '25-54'. The text search parameter "q=" works best when using a single string with no spaces.
https://api.geopath.org/v2.1/segments/catalog?q=25-54
Response:
The response includes a total of 96 segments over 3 sources. It breaks down the result by Source, Category, Sub Categories, and Segments. The response has been truncated for space
{
"sources": [
{
"id": 1,
"name": "Claritas",
"version": "2018",
"description": "Claritas segments",
"categories": [
{
"id": 5,
"name": "Hispanicity",
"description": "Hispanicity",
"subcategories": [
{
"id": 39,
"name": "Coming Soon",
"description": "Coming Soon",
"segments": [
{
"id": 5126,
"id_ads": null,
"id_v1": null,
"available_search": false,
"available_calc": false,
"name": "Hispanicity/Life Stage Segment: Bi-Cultural Hispanic Workforce. Hispanic population between the ages of 25-54 and categorized as HA3",
"description": "Hispanicity/Life Stage Segment: Bi-Cultural Hispanic Workforce. Hispanic population between the ages of 25-54 and categorized as HA3",
"source_id": 1,
"source_name": "Claritas",
"version": "2018",
"category_id": 5,
"category_name": "Hispanicity",
"subcategory_id": 39,
"subcategory_name": "Coming Soon"
},
etc...
}
]
}
]
}
]
},
{
"id": 2,
"name": "Claritas_geopath",
"version": "2018",
"description": "Claritas segments customized by Geopath",
"categories": [
{
"id": 3,
"name": "PopFacts",
"description": "PopFacts",
"subcategories": [
{
"id": 22,
"name": "Population",
"description": "Population",
"segments": [
{
"id": 2023,
"id_ads": null,
"id_v1": null,
"available_search": true,
"available_calc": false,
"name": "Hispanic Persons 25-54 yrs (depreciated)",
"description": "Hispanic Persons 25-54 yrs (depreciated for segment 8374)",
"source_id": 2,
"source_name": "Claritas_geopath",
"version": "2018",
"category_id": 3,
"category_name": "PopFacts",
"subcategory_id": 22,
"subcategory_name": "Population"
},
etc...
]
}
]
}
]
},
{
"id": 3,
"name": "Claritas_Geopath",
"version": "2019",
"description": "Claritas segments customized by Geopath",
"categories": [
{
"id": 6,
"name": "PopFacts",
"description": "PopFacts",
"subcategories": [
{
"id": 98,
"name": "Combined Demographics",
"description": "Standard Segments by Age, HH Income, Ethnicity, Race, Gender",
"segments": [
{
"id": 8530,
"id_ads": "cdae2f39-1c2b-4426-b006-f90216b2ded5",
"id_v1": null,
"available_search": true,
"available_calc": false,
"name": "Females 25-54 yrs HHI $150k+",
"description": "Females 25-54 yrs HHI $150k+",
"source_id": 3,
"source_name": "Claritas_Geopath",
"version": "2019",
"category_id": 6,
"category_name": "PopFacts",
"subcategory_id": 98,
"subcategory_name": "Combined Demographics"
},
etc...
]
}
]
}
]
}
],
"pagination": {
"page": 1,
"page_size": 100,
"number_of_pages": 1,
"next_page": null
}
}
These example 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.
{
"base_segment": "2032",
"target_segment_list": [
"8018"
],
"target_geography_list": [
"CBSA35620"
],
"min_freq": 3,
"batch_list": [
{
"batch_id": "1",
"id_list": [
"310717",
"30450358",
"30496270",
"30790081",
"30492061"
],
"period": {
"start_date": "2020-04-01",
"end_date": "2020-04-07"
}
}
]
}
{
"base_segment": "2032",
"target_segment_list": [
"8018"
],
"target_geography_list": [
"CBSA35620"
],
"min_freq": 3,
"batch_list": [
{
"batch_id": "1",
"id_list": [
"310717",
"30450358",
"30496270",
"30790081",
"30492061"
],
"period": {
"start_date": "2020-04-01",
"end_date": "2020-04-14"
}
}
]
}
{
"base_segment": "2032",
"target_segment_list": [
"8018"
],
"target_geography_list": [
"CBSA35620"
],
"min_freq": 3,
"batch_list": [
{
"batch_id": "1",
"id_list": [
"310717",
"30450358",
"30496270",
"30790081",
"30492061"
],
"period": {
"start_date": "2020-04-01",
"end_date": "2020-04-28"
}
}
]
}
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.
{
"spots_with_no_measures": [],
"measures_summaries": {
"overall": {
"measures_type": "overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.3405391475818913,
"imp_target_inmkt": 3331676.026833938,
"imp_target": 3443587.3304748777,
"imp_inmkt": 3331676.026833938,
"imp": 3443587.3304748777,
"pct_imp_inmkt": 0.967501534620437,
"pct_imp_target_inmkt": 0.967501534620437,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 4.881339052565437,
"reach_net": 997346,
"trp": 16.306304197715143,
"eff_freq_min": 3,
"eff_freq_avg": 5.380610173563891,
"eff_reach_net": 619200,
"eff_reach_pct": 3.030567848574417,
"frames": 5,
"spots": 5,
"summarizes": {
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
"by_batch": [
{
"measures_type": "by_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.3405391475818913,
"imp_target_inmkt": 3331676.026833938,
"imp_target": 3443587.3304748777,
"imp_inmkt": 3331676.026833938,
"imp": 3443587.3304748777,
"pct_imp_inmkt": 0.967501534620437,
"pct_imp_target_inmkt": 0.967501534620437,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 4.881339052565437,
"reach_net": 997346,
"trp": 16.306304197715143,
"eff_freq_min": 3,
"eff_freq_avg": 5.380610173563891,
"eff_reach_net": 619200,
"eff_reach_pct": 3.030567848574417,
"frames": 5,
"spots": 5,
"summarizes": {
"batch_id": "1",
"id_list": [
"310717",
"30450358",
"30492061",
"30496270",
"30790081"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
}
],
"by_spot_overall": [
{
"measures_type": "by_spot_overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.435869283014852,
"imp_target_inmkt": 1183595.48759494,
"imp_target": 1210603.9398637,
"imp_inmkt": 1183595.48759494,
"imp": 1210603.9398637,
"pct_imp_inmkt": 0.9776901004701829,
"pct_imp_target_inmkt": 0.9776901004701829,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 1.6860072740581988,
"reach_net": 344482,
"trp": 5.792900603876168,
"eff_freq_min": 3,
"eff_freq_avg": 5.2776339598945485,
"eff_reach_net": 224266,
"eff_reach_pct": 1.0976321298326486,
"frames": 1,
"spots": 1,
"summarizes": {
"id_list": [
"310717"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 4.580045512824158,
"imp_target_inmkt": 118938.44414043,
"imp_target": 123962.834425674,
"imp_inmkt": 118938.44414043,
"imp": 123962.834425674,
"pct_imp_inmkt": 0.9594685753312898,
"pct_imp_target_inmkt": 0.9594685753312898,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.12709990778621005,
"reach_net": 25968,
"trp": 0.5821233623365957,
"eff_freq_min": 3,
"eff_freq_avg": 5.461167769132948,
"eff_reach_net": 21778,
"eff_reach_pct": 0.10659320257964122,
"frames": 1,
"spots": 1,
"summarizes": {
"id_list": [
"30450358"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.34302023753179,
"imp_target_inmkt": 1295516.92885098,
"imp_target": 1361954.3282199,
"imp_inmkt": 1295516.92885098,
"imp": 1361954.3282199,
"pct_imp_inmkt": 0.9512190695441639,
"pct_imp_target_inmkt": 0.9512190695441639,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 1.8966922199999958,
"reach_net": 387528,
"trp": 6.3406804758290845,
"eff_freq_min": 3,
"eff_freq_avg": 5.179272869434287,
"eff_reach_net": 250134,
"eff_reach_pct": 1.2242414399999846,
"frames": 1,
"spots": 1,
"summarizes": {
"id_list": [
"30492061"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.114549131185019,
"imp_target_inmkt": 501294.670916313,
"imp_target": 511406.734610083,
"imp_inmkt": 501294.670916313,
"imp": 511406.734610083,
"pct_imp_inmkt": 0.9802269641570523,
"pct_imp_target_inmkt": 0.9802269641570523,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.7877541100000052,
"reach_net": 160952,
"trp": 2.453498878887944,
"eff_freq_min": 3,
"eff_freq_avg": 5.215805577315259,
"eff_reach_net": 96110,
"eff_reach_pct": 0.47039692000000466,
"frames": 1,
"spots": 1,
"summarizes": {
"id_list": [
"30496270"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_overall",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.41912391056718,
"imp_target_inmkt": 232330.495331275,
"imp_target": 235659.493355521,
"imp_inmkt": 232330.495331275,
"imp": 235659.493355521,
"pct_imp_inmkt": 0.9858736943848733,
"pct_imp_target_inmkt": 0.9858736943848733,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.4700465618227678,
"reach_net": 96039,
"trp": 1.1371008767853517,
"eff_freq_min": 3,
"eff_freq_avg": 6.948348570184801,
"eff_reach_net": 33436,
"eff_reach_pct": 0.16365052289757376,
"frames": 1,
"spots": 1,
"summarizes": {
"id_list": [
"30790081"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
}
],
"by_spot_batch": [
{
"measures_type": "by_spot_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.435869283014852,
"imp_target_inmkt": 1183595.48759494,
"imp_target": 1210603.9398637,
"imp_inmkt": 1183595.48759494,
"imp": 1210603.9398637,
"pct_imp_inmkt": 0.9776901004701829,
"pct_imp_target_inmkt": 0.9776901004701829,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 1.6860072740581988,
"reach_net": 344482,
"trp": 5.792900603876168,
"eff_freq_min": 3,
"eff_freq_avg": 5.2776339598945485,
"eff_reach_net": 224266,
"eff_reach_pct": 1.0976321298326486,
"frames": 1,
"spots": 1,
"summarizes": {
"batch_id": "1",
"id_list": [
"310717"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 4.580045512824158,
"imp_target_inmkt": 118938.44414043,
"imp_target": 123962.834425674,
"imp_inmkt": 118938.44414043,
"imp": 123962.834425674,
"pct_imp_inmkt": 0.9594685753312898,
"pct_imp_target_inmkt": 0.9594685753312898,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.12709990778621005,
"reach_net": 25968,
"trp": 0.5821233623365957,
"eff_freq_min": 3,
"eff_freq_avg": 5.461167769132948,
"eff_reach_net": 21778,
"eff_reach_pct": 0.10659320257964122,
"frames": 1,
"spots": 1,
"summarizes": {
"batch_id": "1",
"id_list": [
"30450358"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.34302023753179,
"imp_target_inmkt": 1295516.92885098,
"imp_target": 1361954.3282199,
"imp_inmkt": 1295516.92885098,
"imp": 1361954.3282199,
"pct_imp_inmkt": 0.9512190695441639,
"pct_imp_target_inmkt": 0.9512190695441639,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 1.8966922199999958,
"reach_net": 387528,
"trp": 6.3406804758290845,
"eff_freq_min": 3,
"eff_freq_avg": 5.179272869434287,
"eff_reach_net": 250134,
"eff_reach_pct": 1.2242414399999846,
"frames": 1,
"spots": 1,
"summarizes": {
"batch_id": "1",
"id_list": [
"30492061"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 3.114549131185019,
"imp_target_inmkt": 501294.670916313,
"imp_target": 511406.734610083,
"imp_inmkt": 501294.670916313,
"imp": 511406.734610083,
"pct_imp_inmkt": 0.9802269641570523,
"pct_imp_target_inmkt": 0.9802269641570523,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.7877541100000052,
"reach_net": 160952,
"trp": 2.453498878887944,
"eff_freq_min": 3,
"eff_freq_avg": 5.215805577315259,
"eff_reach_net": 96110,
"eff_reach_pct": 0.47039692000000466,
"frames": 1,
"spots": 1,
"summarizes": {
"batch_id": "1",
"id_list": [
"30496270"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
},
{
"measures_type": "by_spot_batch",
"period_days": 7,
"base_segment": "2032",
"target_segment": "2032",
"target_geo": "CBSA35620",
"market": "CBSA35620",
"index_comp_target": 100.0,
"pct_comp_pop_target_inmkt": 1.0,
"pct_comp_imp_target": 1.0,
"pct_comp_imp_target_inmkt": 1.0,
"freq_avg": 2.41912391056718,
"imp_target_inmkt": 232330.495331275,
"imp_target": 235659.493355521,
"imp_inmkt": 232330.495331275,
"imp": 235659.493355521,
"pct_imp_inmkt": 0.9858736943848733,
"pct_imp_target_inmkt": 0.9858736943848733,
"pop_inmkt": 20431828,
"pop_target_inmkt": 20431828,
"reach_pct": 0.4700465618227678,
"reach_net": 96039,
"trp": 1.1371008767853517,
"eff_freq_min": 3,
"eff_freq_avg": 6.948348570184801,
"eff_reach_net": 33436,
"eff_reach_pct": 0.16365052289757376,
"frames": 1,
"spots": 1,
"summarizes": {
"batch_id": "1",
"id_list": [
"30790081"
],
"period": {
"start_date": "2020-04-01T00:00:00.000Z",
"end_date": "2020-04-07T23:59:59.999Z"
}
}
}
]
},
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_summaries": 12
}
}
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.
{
"homes_measures": [
{
"spot_id": 30970663,
"reporting_level": "DMA",
"homes": [
{
"market_id": "DMA514",
"homes_pct": 0.9779435,
"dtm_calculated": "2020-04-13 09:53:02.366 -0400"
},
etc...
]
},
{
"spot_id": 30970678,
"reporting_level": "DMA",
"homes": [
{
"market_id": "DMA514",
"homes_pct": 0.9779435,
"dtm_calculated": "2020-04-13 09:53:02.366 -0400"
}
etc..
]
}
],
"pagination": {
"page": 1,
"page_size": 1000,
"number_of_pages": 1,
"number_of_homes": 250,
"total_number_of_homes": 250
}
}
Geopath supports the ability to retrieve the estimated number of impressions per spot instance, per hour (i.e. the number of times a spot that contained an advertising message was shown on a screen, per hour) for a limited number of audience segments (i.e. P0+/P5+/P18+/P21+), among all persons residing in United States (i.e., without any specific target market geography).
This document will explain how to use Geopath’s API to retrieve hourly impression data regardless of whether the frame/spot is printed/static, tri-vision or digital. This explanation will be easier to understand if the reader has a clear understanding the relationship between frames, layouts, faces, spots and messages; we recommend reviewing OOH Inventory Data Model Hierarch: Frames, Layouts, Faces, and Spots.
A spot is an opportunity to display “creative content”. Creative content can be an image, a video, a textual message, audio, an ad or a combination of these. In Geopath’s terminology, we call “creative content” a message. Geopath does not provide audience measurement for a specific message but instead provides audience measurement for a spot (which may contain a message). For most practical purposes, spot impressions and message impressions are the same, but Geopath would like to ensure the reader understands the subtle distinction between a spot and a message.
Key to understanding how to get hourly impressions for both digital and static spots is understanding the difference between a spot and a spot instance. We can illustrate this concept using an example of a rotating frame. Rotating frames display multiple spots on the same frame by alternately displaying the spots in sequence, one after the other. Both digital frames and tri-vision frames are rotating frames. If we use a simple example of a digital frame with one layout and 6 spots, with each spot displaying for exactly 10 seconds before rotating to the next spot, then each spot would be displayed 60 times in an hour. In Geopath terminology, the duration of a single spot instance is the spot length. And in this example, each spot has a share of voice that is one sixth of the entire rotation time required for all spots to display exactly once.
The API attribute total_msg_impressions represents the average impressions per spot instance per hour this is commonly referred to as the spot multiplier. To convert from average impressions per spot instance per hour (i.e., total_msg_impressions) to impressions per spot per hour, we multiply the API value 'total_msg_impressions' by the number of times a spot is displayed per hour. In the above example for the digital sign, we would multiply total_msg_impressions by 60 (i.e., one time a minute or 60 times an hour).
For a static frame (a printed frame that does not have rotating spots), we can consider that frame as having a spot length (i.e., duration) of 3600 seconds per hour and a share of voice of 1.0, which allows the exact same formula to be used regardless of whether the spot is digital or static:
impressions per spot per hour = total_msg_impressions * number of times a spot is displayed per hour
For a static frame, the number of times the spot is displayed per hour is one. So, in the case of a static sign the average impressions per spot instance per hour is the same as the impressions per spot per hour.
To determine total hourly impressions for a digital spot, we need to determine how many instances of the spot are displayed in an hour. Sticking to the above example with a rotating frame having one layout and one face, and each spot having a length (duration of display) of 10 seconds, the number of spot instances per hour can be calculated by:
spot instances per hour = 3600 / (spots.length * 1/spots.spot_share_of_voice)
so, applying this formula to our example:
3600 seconds / (10 seconds * 1/(1/6)) = 60 spot instances
Assuming the total_msg_impressions in this example were 100 impressions per spot instance per hour, then the hourly impressions for the spot (i.e., all spot instances in the hour) would be
60 * 100 impressions per spot instance per hour = 6000 impressions per spot instance per hour
This calculation holds for the common case where there is only one layout on a frame. To generalize the formula, the layout share of voice must also be used. As an example, let's add in the assumption that there are two layouts on the frame with each layout being displayed for 30 minutes of each hour. In this example, the layout share of voice is 0.5 and the calculation becomes:
spot instances per hour = 3600 / (spots.length * 1/spots.spot_share_of_voice) * layout.share_of_voice
or
30 = 3600 / (10 seconds * 1/(1/6)) * 0.5
Note that the layout.share_of_voice is 1.0 for a static sign, so we can multiply by 1.0 for the layout.share_of_voice for a static frame (or we can omit the multiplication by 1.0 altogether). The general formula for calculating hourly impressions is the same regardless of frame type.
In the 2023 Forecast, served on API v2.2, hourly impressions are currently available for the following core audience segments that include Group Quarters Populations:
All persons 0+ (9330),
All persons 5+ (2038),
All persons 18+ (2035) and
All persons 21+ (2036)
Per spot instance per hour impressions (a.k.a., hourly impressions) are only available for the Global market and are not yet available for local markets. They are available from the https://api.geopath.org/v2.2/inventory/spot/ endpoint and the https://api.geopath.org/v2.2/inventory/search endpoint.
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 impressions for spot identifier 631042 received by any person living anywhere in the united states.
https://api.geopath.org/v2.2/inventory/spot/631042?hourly_measures=true&target_segment=9330
Response:
The response includes total_msg_impressions (aka impressions per spot instance) 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.
{
"id": 631042,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"tue": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"wed": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"thu": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"fri": {
"16": 634.5248,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 781.2816,
"7": 1388.3406,
"8": 1392.8029,
"9": 1318.4193,
"10": 507.4781,
"11": 556.3312,
"12": 603.0401,
"13": 623.1213,
"14": 709.0846,
"15": 688.5293,
"17": 599.181,
"18": 452.4068,
"19": 144.4297,
"20": 0.0,
"21": 0.0
},
"sat": {
"16": 570.7711,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 250.2465,
"7": 498.294,
"8": 760.3759,
"9": 1009.3332,
"10": 683.2922,
"11": 742.2024,
"12": 756.2217,
"13": 731.2883,
"14": 704.7625,
"15": 632.9886,
"17": 514.4061,
"18": 435.6574,
"19": 81.7362,
"20": 0.0,
"21": 0.0
},
"sun": {
"16": 625.1799,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 213.985,
"7": 415.7325,
"8": 675.519,
"9": 994.5795,
"10": 667.1454,
"11": 740.1086,
"12": 761.698,
"13": 747.6507,
"14": 718.2456,
"15": 690.226,
"17": 546.9185,
"18": 454.704,
"19": 98.223,
"20": 0.0,
"21": 0.0
}
}
}
For digital inventory the request and response are the same, but in this case the ID is for a digital spot.
{
"id": 45821,
...
"share_of_voice": 0.125,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"tue": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"wed": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"thu": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"fri": {
"16": 306.387,
"0": 3.1407,
"23": 10.9309,
"1": 3.0309,
"2": 3.4913,
"3": 4.9581,
"4": 7.4025,
"5": 11.168,
"6": 24.1409,
"7": 47.2611,
"8": 55.4073,
"9": 56.9931,
"10": 61.7784,
"11": 72.2067,
"12": 91.3343,
"13": 119.7118,
"14": 204.7374,
"15": 271.6335,
"17": 256.2942,
"18": 143.9799,
"19": 118.5306,
"20": 55.1501,
"21": 26.9983,
"22": 16.3649
},
"sat": {
"16": 119.0891,
"0": 5.9179,
"23": 10.6085,
"1": 5.4012,
"2": 4.9428,
"3": 5.3432,
"4": 7.1372,
"5": 7.2859,
"6": 15.8923,
"7": 34.9228,
"8": 60.0283,
"9": 79.9648,
"10": 94.3997,
"11": 106.9839,
"12": 121.1266,
"13": 142.5048,
"14": 146.1712,
"15": 147.0486,
"17": 87.826,
"18": 67.6795,
"19": 56.4296,
"20": 42.7292,
"21": 28.7425,
"22": 20.1187
},
"sun": {
"16": 74.8528,
"0": 6.1361,
"23": 5.0881,
"1": 5.5246,
"2": 4.8255,
"3": 4.6386,
"4": 5.8287,
"5": 4.695,
"6": 6.8126,
"7": 15.1275,
"8": 27.0525,
"9": 37.1368,
"10": 61.0023,
"11": 64.9546,
"12": 66.3299,
"13": 62.7938,
"14": 60.5499,
"15": 64.6325,
"17": 82.5353,
"18": 54.2426,
"19": 33.2299,
"20": 22.2203,
"21": 10.0552,
"22": 7.0277
}
}
}
Using the above data, we can apply our equation to calculate the hourly impressions per spot:
hourly impressions per spot = total_msg_impressions * ((3600*layout.share_of_voice)/(spots.length/spots.spot_share_of_voice))
In this case, for 5pm local time on Friday (Hour 17) "17": 256.2942, the equation would be as follows:
256.2942 * ((3600*1)/(8/.125))
Which equals 14416.54875 impressions per spot, per hour.
Use Case: Updating hourly measures for only recently updated inventory.
If you've previously requested hourly measures and stored them locally, you may want to update them after inventory has been re-audited and the measures may have changed. In this case, using the inventory/search endpoint will return hourly measures for multiple pieces of inventory.
Call:
This call is similar to other inventory/search calls, but adds the parameter "hourly_measures":true which tells the search that the request wants hourly measures. All other search parameters are available, which is why the request is able to narrow it down to a specific date range and operator. It is important to remember that the hourly_measures are still only available for core audiences and one of those audiences must be specified in the "target_segment" parameter.
{
"parent_account_name_list": [
"JCDecaux"
],
"updated_date_range": {
"start_date": "2020-06-01T00:00:00.000Z",
"end_date": "2020-06-26T23:59:59.000Z"
}
"measures_required":true,
"hourly_measures":true,
"target_segment":9330
}
Response:
The response includes the standard ````inventory/search``` response, but the measures object is expanded to include the "total_msg_impressions" object which details the impressions per play per hour per day of week.This response has been edited for length.
{
"inventory_summary": {
...
"inventory_items": [
{
...
"spot_references": [
{
"spot_id": 30982353,
....
"measures": {
...
},
...
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"tue": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"wed": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"thu": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"fri": {
"16": 1158.0417,
"0": 110.9726,
"1": 92.3966,
"2": 80.0768,
"14": 1384.5434,
"15": 1157.2485,
"11": 1350.9833,
"12": 1378.5591,
"22": 261.1661,
"23": 180.4019,
"3": 84.0225,
"13": 1307.4858,
"21": 296.1627,
"20": 322.397,
"8": 1146.2829,
"9": 1132.8448,
"7": 1173.1396,
"6": 784.5024,
"17": 1077.6308,
"10": 1267.0019,
"4": 108.7172,
"5": 185.2344,
"19": 323.712,
"18": 841.4123
},
"sat": {
"16": 887.9549,
"0": 114.267,
"1": 96.9079,
"2": 83.0552,
"14": 1399.7035,
"15": 911.6171,
"11": 1639.0963,
"12": 1597.8309,
"22": 278.0859,
"23": 198.5225,
"3": 83.1713,
"13": 1464.7111,
"21": 323.2888,
"20": 377.6244,
"8": 811.7533,
"9": 944.6749,
"7": 596.1,
"6": 378.9719,
"17": 843.3488,
"10": 1586.5352,
"4": 104.0201,
"5": 157.6738,
"19": 403.5978,
"18": 718.2194
},
"sun": {
"16": 741.3594,
"0": 176.1774,
"1": 154.8591,
"2": 133.9085,
"14": 815.2282,
"15": 762.7699,
"11": 879.8753,
"12": 908.3486,
"22": 260.4141,
"23": 188.4866,
"3": 128.6869,
"13": 844.2384,
"21": 310.2316,
"20": 432.1372,
"8": 719.4149,
"9": 879.1185,
"7": 502.3611,
"6": 316.7723,
"17": 704.4131,
"10": 832.7391,
"4": 152.3037,
"5": 181.8324,
"19": 493.0984,
"18": 597.6113
}
},
...
}
],
....
},
.....
}
],
"pagination": {
"page": 1,
"page_size": 100,
"number_of_pages": 1,
"number_of_frames": 4,
"number_of_spots": 6
}
}
}
These query ids / links can be used to retrieve bulk downloads of inventory and measures data.
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/{query_id}, is within the URLs below after datasets/
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 specificed file name
A full curl sample
curl -X GET https://assets.geopath.io/datasets/69732E779993C02C31AA497FD05AAF59.json.zip -H "Cache-Control: no-cache" -H "Content-Type: application/json" -H "Geopath-API-Key: YOURAPIKEY" -o /DOWNLOAD/PATH/Folder/all_classification_published_nomeasures_2020_09_14.json.zip
In Postman, you can use the "Send and Download" option to download the zip file.
The description below details what's included within the inventory search and the date it was made. These are the current to the most recent measures release.
For more information on the difference between the PopFacts and Transport Foundry base data, please read this Geopath announcement.
The following bulk files contain data for the 2021 Mid Year Forecast ("2021r1") using the PopFacts data (updated 1/24/2022).
all_classification_published_nomeasures
https://assets.geopath.io/datasets/BCB35ADFA030782E08699E57631093C6.json.zip
all_classification_published_0plus_2021R1
https://assets.geopath.io/datasets/1C5B978842C531CD7B7835A1BF9E854E.json.zip
all_classification_published_0plus_2021R1(LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/E0D498EB924644A24883648188728EBD.json.zip
all_classification_published_5plus_2021R1
https://assets.geopath.io/datasets/AF2FA7D100148F35BCE0648D4F3C937D.json.zip
all_classification_published_5plus_2021R1 (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/6DC551DFC82660D508406BE2B07B2888.json.zip
all_classification_published_18plus_2021R1
https://assets.geopath.io/datasets/58D206FF7A3D8BB8F31BC0DDF36AEE5B.json.zip
all_classification_published_18plus_2021R1 (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/A15D06892FB869C57502CE4D6A774B0D.json.zip
all_classification_published_18plus_2021R1 (LOCAL DMA TARGET MARKET) (14 DAY PERIOD)
https://assets.geopath.io/datasets/7B6AB459A6EC03DA8B7F775BE62A392B.json.zip
all_classification_published_18plus_2021R1 (LOCAL DMA TARGET MARKET) (84 DAY PERIOD)
https://assets.geopath.io/datasets/0F307B56ED85521B8CACDEF99EB8C22D.json.zip
all_classification_published_21plus_2021R1
https://assets.geopath.io/datasets/C5FEC446EC322EF2578A614681DCB6FF.json.zip
all_classification_published_21plus_2021R1 (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/6346548DB32348900FDD246579439D89.json.zip
all_classification_published_21plus_2021R1 (LOCAL DMA TARGET MARKET) (14 DAY PERIOD)
https://assets.geopath.io/datasets/087F700BA2D4486087F3E8A1E33AC1C7.json.zip
all_classification_published_21plus_2021R1 (LOCAL DMA TARGET MARKET) (84 DAY PERIOD)
https://assets.geopath.io/datasets/8310662EA3FACE9A4064343AA49EC89F.json.zip
The following bulk files contain data for the 2021 Mid Year Forecast ("2021r1") using the Transport Foundry combined demographic data (updated 1/24/2022).
all_classification_published_0plus_2021R1_EXCLUDES_GROUP_QUARTERS
https://assets.geopath.io/datasets/FAA4030342CD5FF62C917266211E54BF.json.zip
all_classification_published_0plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/B6E4E62F562C2AC3D798A3CB6785039B.json.zip
all_classification_published_5plus_2021R1_EXCLUDES_GROUP_QUARTERS
https://assets.geopath.io/datasets/28ED672153ECB7F76C576DDF78620EDD.json.zip
all_classification_published_5plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/468A3E3994F2F99FD47AFC3047E3EA02.json.zip
all_classification_published_18plus_2021R1_EXCLUDES_GROUP_QUARTERS
https://assets.geopath.io/datasets/3919F4AC35061911339421406A984891.json.zip
all_classification_published_18plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/68EE6D4DEA60A6ACAC0BF56BF1FDEFCB.json.zip
all_classification_published_18plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET) (14 DAY PERIOD)
https://assets.geopath.io/datasets/FF3458B143513E13576E5297D96E8CAC.json.zip
all_classification_published_18plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET) (84 DAY PERIOD)
https://assets.geopath.io/datasets/D2EDE2887337C215949355426BD08BBA.json.zip
all_classification_published_21plus_2021R1_EXCLUDES_GROUP_QUARTERS
https://assets.geopath.io/datasets/FD9E64ABED042863BFDA276496527ED5.json.zip
all_classification_published_21plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET)
https://assets.geopath.io/datasets/0286EA3354A458EE3F946EDEE2A7D70C.json.zip
all_classification_published_21plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET) (14 DAY PERIOD)
https://assets.geopath.io/datasets/B6E4E62F562C2AC3D798A3CB6785039B.json.zip
all_classification_published_21plus_2021R1_EXCLUDES_GROUP_QUARTERS (LOCAL DMA TARGET MARKET) (84 DAY PERIOD)
https://assets.geopath.io/datasets/7F85A43C11ADF5A1CCA065AB1E4A2C0E.json.zip
Note: the 2021 Midyear forecast became the default API response on 6/21/2021.
Geopath is in the process of updating its annual measures for 2021.
This does not change the measures for 2020 but will be a new dataset that represents the forecast for 2021.
Additionally, Geopath will release an updated midyear forecast for 2021.
Currently when requesting measures, the response returns measures from the January 2021 forecast. The full list of the audiences available for 2021 measures can be found in this Excel file.
Given the accelerated rate of recovery from the COVID-19 Pandemic, Geopath will issue an updated annual forecast in June 2021. This midyear annual forecast will be a 12-month forecast and will reflect the expected audience delivery from June 2021 through May 2022. More information on this here.
While the 2020 and January 2021 data will remain available in the API, it should only be used for historical purposes moving forward. As always, Geopath members should clearly disclose which data vintage is being used when sharing Geopath audience data with other members or clients.
If a use case requires previous measures, a new parameter has been added to all endpoints that return measures. It's detailed in the specific documentation for each endpoint, but on POST endpoints can be referenced as "measures_release" in the request body, and in GET endpoints, can be referenced using "measures_release" as a URL parameter. In either case, the supported values are 2020 or 2021 and "2021r1". If a value other than that is provided, 2025 for example, the API will respond with a 400 error.
The parameter to request 2021 Midyear impressions is "2021r1". This is currently scheduled to become the default release on June 21, 2021
To be clear, the use of this additional parameter is optional. If the parameter is not provided, the response will continue to return the most current released measures. Bulk files will continue to represent the default behavior unless otherwise noted.
Please contact apisupport@geopath.org if you have any questions.