Popcast At Home

Endpoint

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 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
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
    }
}