Popcast™ API

See the documentation of Popcast™ At Home for all details of the data provided by this API.

Endpoints

Cohort Search

cohorts/search

Allows a user to obtain a Motionworks identifier for a specific cohort (this is also called a motionworks_segment_id).

Type

POST

Request Parameters

Required
- motionworks_data_product_name
  - Can be "Popcast at Home" or "Popcast Anytime"
Optional
- search_text
  - Provide a word or phrase to search the cohort descriptions to narrow down the response

Responses

200 OK: Successfully retrieved cohort
404 Not Found: No cohorts can be found

The response is a JSON object with one top-level property:

cohorts: an array of cohort objects.

Each cohort object has two string fields:

motionworks_segment_id – a UUID identifying the segment
cohort_description – a human-readable description of that segment

Example Request

curl --location 'https://intermx-test.apigee.net/v1/cohorts/search' \
--header 'apikey: {YOUR API KEY HERE}' \
--header 'Content-Type: application/json' \
--data '{
  "motionworks_data_product_name": "Popcast At Home",
  "search_text": "video displays"
}'

Example Response

{
    "cohorts": [
        {
            "motionworks_segment_id": "d03b0d5b-7732-4b5e-8cfe-3c59be0537d7",
            "cohort_description": "Places viewed digital video displays past 6 mo Health clubs/fitness centers"
        },
        {
            "motionworks_segment_id": "a6f6f6d3-362b-435d-9f8d-bcdc3718e5b2",
            "cohort_description": "Places viewed digital video displays past 6 months Airplanes"
        },
        {
            "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
            "cohort_description": "Places viewed digital video displays past 6 months Airports"
        },
        {
            "motionworks_segment_id": "6fb69132-84d2-4194-81c4-908c1dd8200b",
            "cohort_description": "Places viewed digital video displays past 6 months Doctors offices/hospitals"
        },
        {
            "motionworks_segment_id": "6ac0d738-a75e-4b1f-aed0-ac59b367b558",
            "cohort_description": "Places viewed digital video displays past 6 months Gas stations"
        }
    ]
}

Popcast At Home Measurement Data

measures/popcast/at_home
Allows a user to obtain a Motionworks Popcast At Home data for a specific cohort (this is also called a motionworks_segment_id) and geography combination.

Type

POST

Request Parameters

Required
- motionworks_segment_id
  - From the above Cohort Search, this is a UUID that identifies the audience cohort
- geography_type
  - Provided as a JSON array, describes the type of geography the data should be aggregated to. Can be "DMA" or "MSA". Only one may be provided.

Responses

200 OK: Successfully retrieved measurement
404 Not Found: measurement with the specified motionworks_segment_id does not exist

The response is a JSON object with properties:

motionworks_segment_id: echo of the provided motionworks_segment_id.
geographic_type: echo of the provided geography_type.
customer_segment_name : the human-readable description of that segment.
year: the year the data is applicable to
persons: the count of persons fitting into the cohort
all_persons: the total population of all the geographies
composition_percent: the percent of the cohort population in the total population
results: a JSON array of each specific geography, and the population measurement within that geography
- Includes the following additional data:
  - geography_id: the Motionworks ID of the geography
  - description: a human-readable description of the geography
  - composition index: the index value of the cohort population vs the population of the geography
  - vintage: the last update of the data
ids: a simpler JSON array restating the population measurements with only the geography_id provided
vintage: the date of the last data run
pagination: details the available pages of the API response

Example Request

curl --location 'https://intermx-test.apigee.net/v1/measures/popcast/at_home' \
--header 'apikey: {YOUR API KEY HERE}' \
--header 'Content-Type: application/json' \
--data '{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geography_type": [
        "DMA"
    ]
}'

Example Response

Note that the results and id arrays are truncated in this example to the first two objects.

{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geographic_type": [
        "DMA"
    ],
    "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
    "year": 2022,
    "persons": 45200906,
    "all_persons": 333633487,
    "composition_percent": 0.13548072289278323,
    "results": [
        {
            "geography_id": "US2020XDMA501",
            "description": "New York, NY",
            "persons": 3917399,
            "all_persons": 22015625,
            "composition_index": 131,
            "composition_percent": 0.177937215046132,
            "geo_type": "DMA",
            "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
            "vintage": "20230909"
        },
        {
            "geography_id": "US2020XDMA803",
            "description": "Los Angeles, CA",
            "persons": 3018582,
            "all_persons": 18369084,
            "composition_index": 121,
            "composition_percent": 0.1643294788134237,
            "geo_type": "DMA",
            "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
            "vintage": "20230909"
        }
    ],
    "ids": [
        {
            "composition_index": 131,
            "composition_percent": 0.177937215046132,
            "geography_id": "US2020XDMA501",
            "persons": 3917399
        },
        {
            "composition_index": 121,
            "composition_percent": 0.1643294788134237,
            "geography_id": "US2020XDMA803",
            "persons": 3018582
        }
    ],
    "vintage": "20230909",
    "pagination": {
        "page": 1,
        "page_size": 100,
        "total": 210,
        "number_of_pages": 3
    }
}

Popcast Anyime Measurement Data

measures/popcast/anyime
Allows a user to obtain a Motionworks Popcast Anytime data for a specific cohort (this is also called a motionworks_segment_id), geography, and time period combination.

Type

POST

Request Parameters

Required
- motionworks_segment_id
  - From the above Cohort Search, this is a UUID that identifies the audience cohort
- geography_type
  - Provided as a JSON array, describes the type of geography the data should be aggregated to. Can be "DMA" or "MSA". Only one may be provided.
- start_date - a number representation of year and month when to start the data aggregation
- start_hour - a number representation of the hour of the day in from 0 to 23 when to start the data aggregation
- end_date - a number representation of year and month when to end the data aggregation
- end_hour a number representation of the hour of the day in from 0 to 23 when to end the data aggregation

Responses

200 OK: Successfully retrieved measurement
400 Bad Request : Invalid request provided
404 Not Found: measurement with the specified motionworks_segment_id does not exist

The response is a JSON object with properties:

motionworks_segment_id: echo of the provided motionworks_segment_id.
geographic_type: echo of the provided geography_type.
customer_segment_name : the human-readable description of that segment.
year: the year the data is applicable to
persons: the count of persons fitting into the cohort in the time range
all_persons: the total population of all the geographies
total_hours_persons: the total population across all hours for the cohort population
total_hours_all_persons: the total population across all hours for everyone in the geographies
composition_percent: the percent of the cohort population in the total population
results: a JSON array of each specific geography, and the population measurement within that geography
- Includes the following additional data:
  - geography_id: the Motionworks ID of the geography
  - description: a human-readable description of the geography
  - composition index: the index value of the cohort population vs the population of the geography
  - vintage: the last update of the data
ids: a simpler JSON array restating the population measurements with only the geography_id provided.
- Includes the following additional data
  - values: an array of the hourly values from the start hour to the end hour of the cohort population in that geography.
vintage: the date of the last data run
pagination: details the available pages of the API response

Example Request

curl --location 'https://intermx-test.apigee.net/v1/measures/popcast/at_home' \
--header 'apikey: {YOUR API KEY HERE}' \
--header 'Content-Type: application/json' \
--data '{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geography_type": [
        "DMA"
    ],
    "start_date": 202301,
    "start_hour": 8,
    "end_date": 202312,
    "end_hour": 20
}'

Example Response

Note that the results and id arrays are truncated in this example to the first two objects.

{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geographic_type": [
        "DMA"
    ],
    "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
    "year": 2023,
    "persons": 45718516,
    "all_persons": 339795010,
    "total_hours_persons": 200247557679,
    "total_hours_all_persons": 1488302605193,
    "composition_percent": 0.13454734370584195,
    "results": [
        {
            "geography_id": "US2020XDMA501",
            "description": "New York, NY",
            "persons": 3905873,
            "all_persons": 21893473,
            "total_hours_persons": 17107727662,
            "total_hours_all_persons": 95893415283,
            "composition_index": 133,
            "composition_percent": 0.17840353606757595,
            "geo_type": "DMA",
            "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
            "vintage": "20240120"
        },
        {
            "geography_id": "US2020XDMA803",
            "description": "Los Angeles, CA",
            "persons": 2997276,
            "all_persons": 18143753,
            "total_hours_persons": 13128072768,
            "total_hours_all_persons": 79469638758,
            "composition_index": 123,
            "composition_percent": 0.16519603193451762,
            "geo_type": "DMA",
            "customer_segment_name": "Places viewed digital video displays past 6 months Airports",
            "vintage": "20240120"
        }
    ],
    "ids": [
        {
            "composition_index": 133,
            "composition_percent": 0.17840353606757595,
            "geography_id": "US2020XDMA501",
            "persons": 3905873,
            "values": [
                3915904,
                3914415,
                3910656,
                3907526,
                3905544,
                3904732,
                3902685,
                3900561,
                3899900,
                3900383,
                3901966,
                3904624
            ]
        },
        {
            "composition_index": 123,
            "composition_percent": 0.16519603193451762,
            "geography_id": "US2020XDMA803",
            "persons": 2997276,
            "values": [
                3002447,
                3000258,
                2998613,
                2996820,
                2994865,
                2992974,
                2991349,
                2990065,
                2992853,
                2997563,
                3002483,
                3005422
            ]
        }
    ],
    "vintage": "20230909",
    "pagination": {
        "page": 1,
        "page_size": 100,
        "total": 210,
        "number_of_pages": 3
    }
}