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](https://docs.foursquare.com/developer/reference/mapi-dataapi-reference) for information on syntax and variables. Report IDs can be discovered using the [/reports](https://docs.foursquare.com/developer/reference/mapi-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
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

```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

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

### Impressions (Multiple Report IDs)

JSON

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

### All Metrics

JSON

```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](https://docs.foursquare.com/developer/reference/mapi-dimensions) page.

### Region

JSON

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

### US State

JSON

```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

```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

```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

```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

```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

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

### Tactic Optimization Metrics

JSON

```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

```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

```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

```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"\
                    ]\
                }\
            ]\
        }\
    ]
}
```