Popcast Anytime

Endpoint

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 percentage 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/anytime' \
--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
    }
}