# Measurement API (MAPI) Documentation

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?](https://docs.foursquare.com/developer/reference/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**](https://docs.foursquare.com/developer/reference/mapi-get-started#base64-encode) your [www.placed.com](http://www.placed.com/) login email and password, separated by a colon (email:password).

### Example  
If an email and password pair is:

Username: `user@foursquare.com`

Password: `hunter2`

First, encode `user@foursquare.com: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:

### macOS/Linux/Unix
```shell
echo -n "email:password" | base64
```

### Windows (Command Prompt)
```shell
echo email:password | certutil -encodebase64 -
```

### Windows (PowerShell)
```text
[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  
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](https://docs.foursquare.com/developer/reference/mapi-get-started#data) and [Reports](https://docs.foursquare.com/developer/reference/mapi-get-started#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`.

`reportIds` can be retrieved from the the [`reports`](https://docs.foursquare.com/developer/reference/mapi-get-started#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
```curl
curl -X POST "https://mapi.placed.com/data" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{\n    "reportIds": [\
        "abc123" // get this from /reports endpoint\
    ],\n    "metrics": [\
        { "name": "impressions" }\
    ]\n}'
```

**Request an overview of metrics filtered by certain line items, with top-level metrics by State**:
cURL
```curl
curl -X POST "https://mapi.placed.com/data" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{\n    "reportIds": [\
        "INSERT REPORT ID HERE"\
    ],\n    "metrics": [\
        { "name": "impressions" },\
        { "name": "reach" },\
        { "name": "frequency" },\
        { "name": "spend" },\
        { "name": "cvr" },\
        { "name": "visits" },\
        { "name": "cpv" },\
        { "name": "lift" },\
        { "name": "liftConfidence" },\
        { "name": "behavioralLift" },\
        { "name": "behavioralLiftConfidence" }\
    ],\n    "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"\
    ]\n  }'
```

## Reports  
The request body for the `reports` endpoint can contain any filters that would help find your report.

**Pull all reports**:
cURL
```curl
curl -X POST "https://mapi.placed.com/reports" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{\n      "page": 1,\n      "perPage": 1000\n    }'
```

**Pull live campaigns by advertiser**:
cURL
```curl
curl -X POST "https://mapi.placed.com/reports" \
-H "Authorization: Basic <your_base64_encoded_credentials>" \
-H "Content-Type: application/json" \
-d '{\n  "page": 1,\n  "perPage": 50,\n  "filters": [\
    {\
      "predicates": [\
        {\
          "dimension": { "name": "status" },\
          "operator": { "name": "in" },\
          "values": ["processing"]\
        }\
      ]\
    },\
    {\
      "dimension": { "name": "advertiser" },\
      "operator": { "name": "IN" },\
      "values": ["ENTER ADVERTISER NAME HERE"]\
    }\
  ]\n}'
```

# Responses  
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/data](https://mapi.placed.com/data)
- [https://mapi.placed.com/data/{requestId}](https://mapi.placed.com/data/%7BrequestId%7D)

CSV
- [https://mapi.placed.com/data.csv](https://mapi.placed.com/data.csv)
- [https://mapi.placed.com/data/{requestId}.csv](https://mapi.placed.com/data/%7BrequestId%7D.csv)

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](https://mapi.placed.com/reports)
- CSV: [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 the `perPage` key.