Examples & Templates

This page demonstrates sample queries for the /data endpoint. You can modify and use these queries for your own purposes.

Refer to the API Reference for information on syntax and variables. Report IDs can be discovered using the /reports endpoint as necessary.

Example Query

The below examples and templates are formatted as a JSON object, which is passed via the request's body.

Here is what a complete query to the Measurement API looks like. Again, notice the JSON contains all the parameters for your query.

cURL

curl -X POST "https://mapi.placed.com/data" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{
    "reportIds": [\
        "[your_report_id]" // get this from /reports endpoint\
    ],
    "metrics": [\
        { "name": "impressions" }\
    ]
}'

PHP

$url = "https://mapi.placed.com/data";
$ch = curl_init($url);
$cred = base64_encode("<your username>:<your password>");
$headers = array(
    "Authorization: Basic " . $cred,
    "Content-Type: application/json"
);
$payload = '{
    "reportIds": [\
        "abc123" // get this from /reports endpoint\
        ],
    "metrics": [\
        { "name": "impressions" }\
    ]
}';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$output = curl_exec($ch);
var_dump(json_decode($output));
curl_close($ch);

General

Impressions

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "impressions" }\
  ]
}

Impressions (Multiple Report IDs)

JSON

{
  "reportIds": [\
    "<REPORT-ID-1>",\
    "<REPORT-ID-2>",\
    "<REPORT-ID-3>"\
  ],
  "metrics": [\
    { "name": "impressions" }\
  ]
}

All Metrics

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "impressions" },\
    { "name": "reach" },\
    { "name": "frequency" },\
    { "name": "spend" },\
    { "name": "cvr" },\
    { "name": "visits" },\
    { "name": "cpv" },\
    { "name": "lift" },\
    { "name": "liftConfidence" },\
    { "name": "behavioralLift" },\
    { "name": "behavioralLiftConfidence" }\
  ]
}

Breakouts by Dimension

Dimensions help categorize and filter data for detailed analysis and reporting. For a full list of dimensions available from the Measurement API, see the Dimensions page.

Region

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "behavioralLift" }\
  ],
  "dimensions": [\
    { "name": "region"}\
  ]
}

US State

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "impressions" },\
    { "name": "reach" },\
    { "name": "frequency" },\
    { "name": "spend" },\
    { "name": "cvr" },\
    { "name": "visits" },\
    { "name": "cpv" },\
    { "name": "liftConfidence" },\
    { "name": "behavioralLift" },\
    { "name": "behavioralLiftConfidence" }\
  ],
  "dimensions": [\
    { "name": "state"}\
  ]
}

Media Partner

JSON

{
    "reportIds": [\
        "<REPORT-ID>" // The partner dimension is best used in conjunction with "Custom" reports; Partner-level report IDs will only return data for the given partner\
        ],
    "metrics": [\
        { "name": "impressions" },\
        { "name": "reach" },\
        { "name": "freq" },\
        { "name": "spend" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "costPerStoreVisit" },\
        { "name": "liftIndex" },\
        { "name": "liftConfidence" },\
        { "name": "behavioralLiftIndex" },\
        { "name": "behavioralLiftConfidence" }\
    ],
    "dimensions": [\
        { "name": "partner" }\
    ]
}

Historical Visitation Cohorts

JSON

Demographics

JSON

{
    "reportIds": [\
        "<REPORT-ID>"\
        ],
    "metrics": [\
        { "name": "impressions" },\
        { "name": "reach" },\
        { "name": "freq" },\
        { "name": "spend" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "costPerStoreVisit" },\
        { "name": "liftIndex" },\
        { "name": "liftConfidence" },\
        { "name": "behavioralLiftIndex" },\
        { "name": "behavioralLiftConfidence" }\
    ],
    "dimensions": [\
        { "name": "gender" }\
    ]
}

TV Network

JSON

{
    "reportIds": [\
        "INSERT REPORT ID HERE"\
        ],
    "metrics": [\
        { "name": "impressions" },\
        { "name": "reach" },\
        { "name": "freq" },\
        { "name": "spend" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "costPerStoreVisit" },\
        { "name": "liftIndex" },\
        { "name": "liftConfidence" },\
        { "name": "behavioralLiftIndex" },\
        { "name": "behavioralLiftConfidence" }\
    ],
    "dimensions": [\
        { "name": "network" }\
    ]
}

Tactics and Line Items

Line Item Volume & Performance

JSON

{
    "reportIds": [\
        "<REPORT-ID>"\
        ],
    "metrics": [\
        { "name": "impressions" },\
        { "name": "spend" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "costPerStoreVisit" },\
        { "name": "cpblv" }, //cost per behavioral lift store visit\
        { "name": "behavioralLiftIndex" }, //the lineItem dimension requires the use of indices for fetching lift metrics\
        { "name": "behavioralLiftConfidence" }\
    ],
    "dimensions": [\
        { "name": "lineItem" }\
    ]
}

Impressions by Tactic

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "impressions" }\
  ],
  "dimensions": [\
    { "name": "tactic" }\
  ]
}

Tactic Optimization Metrics

JSON

{
  "reportIds": [\
    "<REPORT-ID>"\
  ],
  "metrics": [\
    { "name": "optimization_index" },\
    { "name": "t_score" },\
    { "name": "lift_confidence_t_score" },\
    { "name": "new_visitation_confidence_t_score" }\
  ],
  "dimensions": [\
    { "name": "tactic" }\
  ]
}

Custom Reporting (Filters)

Filter Report to Line Items

JSON

{
    "reportIds": [\
        "<REPORT-ID>"\
    ],
    "metrics": [\
        { "name": "impressions" }\
    ],
    "filters": [\
        {\
            "predicates": [\
                {\
                    "type": "media",\
                    "dimension": { "name": "lineItem" },\
                    "operator": { "name": "in" },\
                    "values": [\
                        "ENTER LINE ITEM ID HERE",\
                        "ENTER LINE ITEM ID HERE"\
                    ]\
                }\
            ]\
        }\
    ]
}

Filter Report to Tactics

JSON

{
    "reportIds": [\
        "<REPORT-ID>"\
    ],
    "metrics": [\
        { "name": "impressions" }\
    ],
    "filters": [\
        {\
            "predicates": [\
                {\
                    "type": "media",\
                    "dimension": { "name": "tactic" },\
                    "operator": { "name": "in" },\
                    "values": [\
                        "ENTER TACTIC ID HERE",\
                        "ENTER TACTIC ID HERE"\
                    ]\
                }\
            ]\
        }\
    ]
}

Publisher-Unique Audience Performance

JSON

{
    "reportIds": [\
        "<REPORT-ID>" // In most cases, this will be the full campaign summary report ID. Custom Reports can also be used.\
    ],
    "metrics": [\
        { "name": "impressions" },\
        { "name": "reach" },\
        { "name": "freq" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "behavioralLift" },\
        { "name": "costPerStoreVisit" }\
    ],
    "filters": [\
        {\
            "predicates": [\
                {\
                    "type": "user",\
                    "dimension": { "name": "partner" },\
                    "operator": { "name": "in" },\
                    "values": [\
                        "REPORT ID" // Use the Report ID which corresponds to the partner who you want unique metrics for\
                    ]\
                },\
                {\
                    "type": "user",\
                    "dimension": { "name": "partner" },\
                    "operator": { "name": "not_in" },\
                    "values": [\
                        "REPORT ID", // This array should have every partner report ID excepting the one from the previous filter\
                        "REPORT ID",\
                        "REPORT ID",\
                        "REPORT ID"\
                    ]\
                }\
            ]\
        }\
    ]
}