API Docs
Support

Get Started

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 the reports endpoint.

Alternatively, you may find the reportId from the report URL. To get the reportId 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:

📘

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 the perPage key. Both keys are described in the Request table below.