API Docs
Support

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 -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" }
    ]
}'


$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

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

Impressions (Multiple Report IDs)

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

🔎

Meta-analyses: Extra Step for Retrieval

When requesting a metric across multiple reports, an extra step is required to retrieve your data. Learn more.

All Metrics

{
  "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

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

US State

{
  "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

{
    "reportIds": [
        "<REPORT-ID>" // The partner dimension is best used in conjuction 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

{
    "reportIds": [
        "<REPORT-ID>" // The partner dimension is best used in conjuction 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": "audience" }
    ]
}

Demographics

Return all metrics by demographics. For other demographic cuts, try "age", "income", and more. 

{
    "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

For other Linear TV specific dimensions, try "networkDaypart", "dayDaypart", and more.

{
    "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" } // For other Linear TV specific dimensions, see the resource center, or try "networkDaypart", "dayDaypart"       
    ]
}

Tactics and Line Items

Line Item Volume & Performance

{
    "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 indeces for fetching lift metrics
        { "name": "behavioralLiftConfidence" }
    ],
    "dimensions": [
        { "name": "lineItem" }
    ]
}

Impressions by Tactic

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

Tactic Optimization Metrics

This example retrieves the Optimization Index, T-Score, Lift Confidence T-Score, and New Visitation Confidence T-Score broken out by Tactic for a given Report ID.

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

🚧

Tactic dimensions requires optimization!

The tactic dimension is only available when optimization is enabled for the placement. If queried on a non-enabled placement, the response from the server will be: `

{
  "error": {
    "dimensions": [
      "Optimization is not enabled for this placement"
    ]
  }
}

Custom Reporting (Filters)

Filter Report to Line Items

You can add additional IDs using comma-separation as shown below.

{
    "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

{
    "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

{
    "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"
                    ]
                },
            ]       
        }
    ]
}