Welcome to the Measurement API (MAPI) documentation.
Not sure what the Measurement API is?
Read about the Measurement API's use cases on the What is MAPI? page.
Host
Foursquare's Measurement API is hosted at https://mapi.placed.com
.
Authentication
MAPI supports basic HTTP authentication.
Requests are authorized using data provided in the request's Authorization header.
Format
Authorization: Basic <credentials>
For the credentials value, Base64 encode your www.placed.com login email and password, separated by a colon (email:password).
Example
If an email and password pair is:
Username: [email protected]
Password: hunter2
First, encode [email protected]:hunter2
in base64, producing dXNlckBmb3Vyc3F1YXJlLmNvbTpodW50ZXIy
.
Then, complete the authorization header: Authorization: Basic dXNlckBmb3Vyc3F1YXJlLmNvbTpodW50ZXIy
.
Base64 Encode
Encoding your login credentials is a very simple process. Select your operating system to see how to encode your credentials locally:
echo -n "email:password" | base64
echo email:password | certutil -encodebase64 -
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("email:password"))
Alternatively, you can use one of the many available online tools to Base64 encode your login information. While many online tools transmit data securely and are safe to use, please exercise caution when entering any sensitive password information to the tools. Encoding locally via the commands above is the safest method.
API Requests
Try the API in a few clicks!
The API explorer lets you use the Measurement API from the browser. Try it:
To interact with the Data or Reports API, include the following components in your request:
- Authentication: The Base64-encoded credentials in the authorization header.
- Request Body: Endpoint-specific parameters in the request body.
While your authentication is the same for both the Data or Reports API, the request body varies between Data and Reports endpoints.
Data
The request body for the Data endpoint should contain the reportIds
for the reports you wish to pull data from. You can further filter your results by specifying dimensions
and filters
.
Find
reportIds
reportIds
can be retrieved from the thereports
endpoint.Alternatively, you may find the
reportId
from the report URL. To get thereportId
from your browser's URL, navigate to your report, and copy only the 32-digit alphanumeric string.Example
reportId
:2adf34d-br4d-93dc-0d03-ao09d5p2jko0
Examples
Pull impression metrics from a report:
curl -X POST "https://mapi.placed.com/data" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{
"reportIds": [
"abc123" // 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);
Request an overview of metrics filtered by certain line items, with top-level metrics by State:
curl -X POST "https://mapi.placed.com/data" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{
"reportIds": [
"INSERT REPORT ID HERE"
],
"metrics": [
{ "name": "impressions" },
{ "name": "reach" },
{ "name": "frequency" },
{ "name": "spend" },
{ "name": "cvr" },
{ "name": "visits" },
{ "name": "cpv" },
{ "name": "lift" },
{ "name": "liftConfidence" },
{ "name": "behavioralLift" },
{ "name": "behavioralLiftConfidence" }
],
"filters": [
{
"predicates": [
{
"type": "media",
"dimension": { "name": "lineItem" },
"operator": { "name": "in" },
"values": [
"ENTER LINE ITEM ID HERE",
"ENTER LINE ITEM ID HERE" // You can add additional IDs using comma-separation as shown
]
}
]
}
],
"dimensions": [
{ "name": "state" } // For other geographical cuts, use "region" or "market"
]
}'
$url = "https://mapi.placed.com/data";
$ch = curl_init($url);
$cred = base64_encode("<username>:<password>");
$headers = array(
"Authorization: Basic " . $cred,
"Content-Type: application/json"
);
$payload = '{
"reportIds": [
"INSERT REPORT ID HERE"
],
"metrics": [
{ "name": "impressions" },
{ "name": "reach" },
{ "name": "frequency" },
{ "name": "spend" },
{ "name": "cvr" },
{ "name": "visits" },
{ "name": "cpv" },
{ "name": "lift" },
{ "name": "liftConfidence" },
{ "name": "behavioralLift" },
{ "name": "behavioralLiftConfidence" }
],
"filters": [
{
"predicates": [
{
"type": "media",
"dimension": { "name": "lineItem" },
"operator": { "name": "in" },
"values": [
"ENTER LINE ITEM ID HERE",
"ENTER LINE ITEM ID HERE" // You can add additional IDs using comma-separation as shown
]
}
]
}
],
"dimensions": [
{ "name": "state" } // For other geographical cuts, use "region" or "market"
]
}';
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);
Reports
The request body for the reports
endpoint can contain any filters that would help find your report.
Pull all reports:
curl -X POST "https://mapi.placed.com/reports" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{
"page": 1,
"perPage": 1000
}'
$url = "https://mapi.placed.com/reports";
$ch = curl_init($url);
$cred = base64_encode("<username>:<password>");
$payload =
'{
"page": 1,
"perPage": 1000
}';
$headers = array("Authorization: Basic " . $cred,
"Content-Type:application/json");
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);
Pull live campaigns by advertiser:
curl -X POST "https://mapi.placed.com/reports" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{
"page": 1,
"perPage": 50,
"filters": [
{
"predicates": [
{
"dimension": { "name": "status" },
"operator": { "name": "in" },
"values": ["processing"]
}
]
},
{
"dimension": { "name": "advertiser" },
"operator": { "name": "IN" },
"values": ["ENTER ADVERTISER NAME HERE"]
}
]
}'
$url = "https://mapi.placed.com/reports";
$ch = curl_init($url);
$cred = base64_encode("<username>:<password>");
$payload = '{
"page": 1,
"perPage": 50,
"filters": [
{
"predicates": [
{
"dimension": { "name": "status" },
"operator": { "name": "in" },
"values": ["processing"]
}
]
},
{
"dimension": { "name": "advertiser" },
"operator": { "name": "IN" },
"values": ["ENTER ADVERTISER NAME HERE"]
}
]
}';
$headers = array("Authorization: Basic " . $cred,
"Content-Type:application/json");
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);
Responses
Data
The default responses for these endpoints are delivered in JSON format. To request a CSV formatted response, simply append the format to the URL as shown:
JSON (default):
CSV
Meta-Analysis (Multiple Report IDs)
In some cases, you may want to request a metric across more than one Report ID. This is known as "Meta-Analysis," and requires an additional step to retrieve the results of the query.
Reports
The default responses for these endpoints are delivered in JSON format. To request a CSV formatted response, simply append the format to the URL as shown:
- JSON (default): https://mapi.placed.com/reports
- CSV: https://mapi.placed.com/reports.csv
Pagination
The response from the /reports endpoint is paginated, returning the first page of results with 50 rows per page by default. The result page can be changed using the
page
key, and the result count per page can be increased to up to 100 rows using theperPage
key. Both keys are described in the Request table below.