Placecast™ Select API

See the documentation of Placecast™ Select for all details of the data provided by this API.

Endpoints

Project List

projects

Allows a user to retrieve all projects associated with the specified API key. API keys are unique to each user and account.

Type

GET

Request Parameters

None

Responses

200 OK: Successfully retrieved the list of projects
404 Not Found: No project found

The response is a JSON array of objects with details of the projects associated to the api key.

Example Request

curl --location 'https://intermx-test.apigee.net/v1/cohorts/search' \
--header 'apikey: {YOUR API KEY HERE}'

Example Response

{
    "pagination": {
        "total": 1,
        "found": 1,
        "page": 1,
        "perPage": 1000,
        "pageSize": 1
    },
    "projects": [
        {
            "_id": "67f93188127def0013f5bb79",
            "name": "Boardwalk 2024",
            "createdAt": "2025-04-11T15:13:12.142Z",
            "updatedAt": "2025-04-14T22:18:11.773Z"
        }
    ]
}

Scenario List

scenarios

Allows a user to retrieve all projects associated with the specified API key. API keys are unique to each user and account.

Type

GET

Request Parameters

Optional
- project: The identifier of a specific project obtained from the project list endpoint, provided as a url parameter to the GET request.

Responses

200 OK: Successfully retrieved the list of scenarios
404 Not Found: No scenarios found

The response is a JSON array of objects with details of the scenarios associated to the api key, and if provided the specific project.

Example Request

curl --location 'https://intermx-prod.apigee.net/v1/scenarios?project=67f93188127def0013f5bb79' \
--header 'apikey: {YOUR API KEY HERE}'

Example Response

{
    "pagination": {
        "total": 366,
        "page": 1,
        "perPage": 10,
        "pageSize": 10
    },
    "results": [
        {
            "_id": "67fd89a398c90f0012429fcc",
            "name": "Atlantic City Boardwalk - 2024-12-31",
            "description": "Atlantic City Boardwalk - 2024-12-31",
            "createdAt": "2025-04-14T22:18:11.612Z",
            "updatedAt": "2025-04-14T22:18:11.804Z"
        },
        {
            "_id": "67fd8997ebf1d60012f67e2b",
            "name": "Atlantic City Boardwalk - 2024-12-22",
            "description": "Atlantic City Boardwalk - 2024-12-22",
            "createdAt": "2025-04-14T22:17:59.797Z",
            "updatedAt": "2025-04-14T22:18:00.021Z"
        }
    ]
}

Scenario Info

scenarios/{scenario_id}

Allows a user to retrieve information about a specific scenario request.

Type

GET

Request Parameters

Required
- {scenario_id}: The identifier of a specific scenario obtained from the scenario list endpoint, provided as part of the request URL.

Responses

200 OK: Successfully retrieved the scenario
404 Not Found: Scenario with the specified ID does not exist

The response is a JSON object with properties related to the requested scenario.

Example Request

curl --location 'https://intermx-prod.apigee.net/v1/scenarios/67fc957b1390410012509651' \
--header 'apikey: {YOUR API KEY HERE}'

Example Response

{
    "name": "Atlantic City Boardwalk - 2024-01-02",
    "description": "Atlantic City Boardwalk - 2024-01-02",
    "motionworks_scenario_id": "06C937FB-ED5A-4BE1-B6F9-57A8BA28FE4A",
    "modified": "2025-04-14T04:56:27+00:00",
    "created": "2025-04-14T04:56:27+00:00",
    "periods": [
        {
            "period_name": "1/2/2024 12:00 AM - 1/2/2024 11:45 PM",
            "start_time": "2024-01-02T00:00:00+00:00",
            "end_time": "2024-01-02T23:45:00+00:00"
        }
    ],
    "place_ids": [
        "276411"
    ],
    "cohort": {
        "geography_ids": [
            "XX2020NATNUS"
        ],
        "motionworks_segment_id": "23b327e2-b9f2-4d23-9930-ac1f8621a75a"
    },
    "customer": {
        "customer_id": "203",
        "customer_name": "All Points Media",
        "customer_scenario_id": "828e9f5d7cbb42c68cfdb94d71ce7d00ae1483f6",
        "customer_scenario_name": "Atlantic City Boardwalk - 2024-01-02",
        "customer_scenario_info": "Atlantic City Boardwalk Info - 2024-01-02"
    },
    "runtime_version": "2.3",
    "include_cohort_metrics": true,
    "include_confidence_interval": true,
    "timezone": "America/New_York"
}

Scenario Measures Report

scenarios/{scenario_id}

Allows a user to retrieve measurement data about a specific scenario.

Type

POST

Request Parameters

Required
- {scenario_id}: The identifier of a specific scenario obtained from the scenario list endpoint, provided as a JSON object.

Responses

200 OK: Successfully retrieved scenario measurement report
404 Not Found: Scenario report with the specified ID does not exist

The response is a JSON object with measurement related to the requested scenario.

Example Request

curl -X POST 'https://intermx-prod.apigee.net/v1/measures/placecast/scenario' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{"scenario_id":"06C937FB-ED5A-4BE1-B6F9-57A8BA28FE4A"}'

Example Response

Note this example has null measurements

{
    "scenario": {
        "motionworks_scenario_id": "06C937FB-ED5A-4BE1-B6F9-57A8BA28FE4A",
        "periods": [
            {
                "end_time": "2024-01-02T23:45:00Z",
                "start_time": "2024-01-02T00:00:00Z",
                "period_name": "1/2/2024 12:00 AM - 1/2/2024 11:45 PM"
            }
        ],
        "scenario_published": "2025-04-14 08:28:46.697276+00",
        "measured_places": 1,
        "timezone": "",
        "cohort": {
            "home_geography_ids": [
                "XX2020NATNUS"
            ],
            "home_geography_names": [
                "United States"
            ],
            "motionworks_base_segment_id": "23b327e2-b9f2-4d23-9930-ac1f8621a75a",
            "motionworks_base_segment_name": ""
        },
        "visits": 0,
        "visits_ci": [
            0,
            0
        ],
        "visits_total": 0,
        "visits_unique": 0,
        "visits_unique_total": 0,
        "dropoffs": 0,
        "dropoffs_ci": [
            0,
            0
        ],
        "dropoffs_total": 0,
        "passbys": 0,
        "passbys_ci": [
            0,
            0
        ],
        "passbys_total": 0,
        "activities": 0,
        "activities_ci": [
            0,
            0
        ],
        "activities_total": 0,
        "activities_unique": 0,
        "activities_unique_total": 0,
        "exposures": 0,
        "exposures_ci": [
            0,
            0
        ],
        "exposures_total": 0,
        "exposures_unique": 0,
        "exposures_unique_total": 0,
        "exposures_visitors": 0,
        "event_minutes_visitors": 0,
        "percent": {
            "dwell_bins": [],
            "dwell_plus": [],
            "event_time_plus": [],
            "day": [],
            "segment": {
                "basic_demographics": null,
                "consumer": null,
                "customer": null,
                "other": []
            },
            "home": {
                "state_province": null,
                "dma": null,
                "metro_area": null,
                "county": null,
                "postal_code": null,
                "census_neighborhood": null
            }
        },
        "messages": {
            "message": "",
            "dropped_places": []
        },
        "debug_internal": {}
    },
    "places": []
}

Create Scenario

scenarios

Allows a user to retrieve information about a specific scenario request.

Type

POST

Request Parameters

Required
- motionworks_scenario_id - A unique identifier for the request. If the same identifier is used, data will be overwritten.
- customer_id - please contact us for your customer id
- customer_scenario_id - a customer provided identifier for customer use
- timezone - the timezone of the defined period
- place_ids - an array of specific place ids that are being measured
- periods - an array of specific time periods the places should be measured for
Optional
- project: The identifier of a specific project as obtained from the project list endpoint. Provide as a URL parameter to the request

Responses

200 OK: Successfully retrieved the scenario
404 Not Found: Scenario with the specified ID does not exist

The response is a JSON object with properties related to the requested scenario.

Example Request

curl -X POST 'https://intermx-prod.apigee.net/v1/measures/placecast/scenario' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
  "name": "Atlantic City Boardwalk - 2024-01-02",
  "description": "Atlantic City Boardwalk - 2024-01-02",
  "motionworks_scenario_id": "C42AA2BB-173F-423E-9AFF-518BB9D7486C",
  "periods": [
    {
      "period_name": "2024-01-02 12:00 AM - 2024-01-02 11:45 PM",
      "start_time": "2024-01-02T05:00:00+00:00",
      "end_time": "2024-01-03T04:45:00+00:00"
    }
  ],
  "place_ids": [
    "276411"
  ],
  "cohort": {
    "geography_ids": [
      "XX2020NATNUS"
    ],
    "motionworks_segment_id": "23b327e2-b9f2-4d23-9930-ac1f8621a75a"
  },
  "customer": {
    "customer_id": "203",
    "customer_name": "All Points Media",
    "customer_scenario_name": "Atlantic City Boardwalk - 2024-01-02",
    "customer_scenario_info": "Atlantic City Boardwalk Info - 2024-01-02",
    "customer_scenario_id": "C42AA2BB-173F-423E-9AFF-518BB9D7486C"
  },
  "timezone": "America/New_York",
  "runtime_version": "2.3",
  "include_cohort_metrics": true,
  "include_confidence_interval": true
}'

Example Response

{
    "status": "success",
    "api-message": "Atlantic City Boardwalk - 2024-01-02' added successfully to Project 'Sandbox'",
    "message": "Scenario 'Atlantic City Boardwalk - 2024-01-02' added successfully to Project 'Sandbox'",
    "data": {
        "id": {
            "project": "64b5968db4b3cd0012d66b50",
            "scenario": "6812e0f57661f800126de44b"
        },
        "name": "Atlantic City Boardwalk - 2024-01-02"
    }
}

Delete Scenario

/scenarios/{scenario_id}

Allows a user to delete a specific scenario from their account. Note that the scenario will be "soft-deleted" or just dis-associated from the user's account.

Type

DELETE

Request Parameters

Required:
- scenario_id: Identifer for the scenario as obtained from the Scenario List endpoint

Responses

200 OK: Successfully deleted scenario.
404 Not Found: Error in deletion attempt

Example Request

curl --location --request DELETE 'https://intermx-prod.apigee.net/v1/scenarios/681194583aad62001286c4c4' \
--header 'apikey: {YOUR API KEY HERE}'

Example Response

{"status_code": 200}