### [Click here](https://docs.foursquare.com/developer/reference/mapi-reports-api-reference) to view API documentation concerning the `/reports` endpoint

The /data endpoint allows you to find and retrieve Attribution report metrics for one or more reports.

If you request data for a single report, the result will be returned to you synchronously. If you request data for multiple reports, the result will be made available at our /data/{requestId} endpoint. These results will be available for 30 days. More information about these workflows can be found in [Examples & Templates](https://docs.foursquare.com/developer/reference/examples-templates-1).

* * *

# Formatted Responses

The default responses are provided in JSON format. For a CSV formatted response, add ".csv" to the URL:

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)

* * *

# /data Endpoint

| Endpoint     | Verb  | Body                                 | Accepts |
|--------------|-------|--------------------------------------|---------|
| `/data`      | `POST`| [Request](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#request) | JSON    |

## Request

| key        | type   | description                                                                                                 |
|------------|--------|-------------------------------------------------------------------------------------------------------------|
| `reportIds`| Array  | Array of Placement or Custom Report IDs. If a single reportId is specified, the result will be returned synchronously. If multiple `reportIds` are specified, the result will be returned asynchronously. |
| `metrics`  | Array  | Array of [`metric`](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#metric)        |
| `dimensions`| Array | Array of [`dimensions`](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#dimensions) |
| `filters`  | Array  | Array of [`filter`](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#filter) Currently one filter is supported at a time. A filter may have more than one [Predicate](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#predicate) |
| `options`  | Object | [`requestOptions`](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#requestoptions) |

### Metric

| key    | type   | description                                           |
|--------|--------|-------------------------------------------------------|
| `name` | String | [Available Metrics](https://docs.foursquare.com/developer/reference/mapi-metrics) |

### Dimension

| key    | type   | description                                          |
|--------|--------|------------------------------------------------------|
| `name` | String | [Available Dimensions](https://docs.foursquare.com/developer/reference/mapi-dimensions) |

### Filter

| key        | type   | description                                             |
|------------|--------|---------------------------------------------------------|
| `predicates`| Array | Array of [Predicate](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#predicate). The data returned by this request will satisfy all of the given Predicates. |

### Predicate

| key        | type   | description                                            |
|------------|--------|--------------------------------------------------------|
| `dimension`| Object | [Dimensions](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#dimension) |
| `operator` | Object | [Operator](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#operator) |
| `values`   | Array  | Array of values to be used by the operator function. |

### Operator

| key    | type   | description                            |
|--------|--------|----------------------------------------|
| `name` | String | `IN`, `NOT_IN`, `BETWEEN`, `LIKE`, `GREATER_THAN`, `LESS_THAN` |

### RequestOptions

| key                        | type    | description                                                                        |
|---------------------------|---------|------------------------------------------------------------------------------------|
| `includeQueryInResponse`  | Boolean | Set to `true` if you would like your request/query included in your response. |

## Response

| key     | type    | description                                                              |
|---------|---------|--------------------------------------------------------------------------|
| `result`| Object  | [Result](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#result) A Result is returned if the request is complete. (This object has the same structure as the Result returned from the /data endpoint) |
| `status`| Object  | [Status](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#status) |

### Result

| key     | type    | description                                                                 |
|---------|---------|-----------------------------------------------------------------------------|
| `data`  | Object  | [Data](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#data) |
| `query` | Object  | [Request](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#status) Included if original request's `includeQueryInResponse` option is set to `true` |

### Data

| key      | type    | description                                                                       |
|----------|---------|-----------------------------------------------------------------------------------|
| `columns`| Array   | Array of [Column](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#column) |
| `rows`   | Array   | Array of [Row](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#row) |

### Column

| key      | type    | description                                            |
|----------|---------|--------------------------------------------------------|
| `name`   | String  | Report ID, Dimension or Metric Name                   |
| `type`   | String  | `REPORT_ID`, `DIMENSION`, `METRIC`                   |

### Row

| key      | type    | description                                     |
|----------|---------|-------------------------------------------------|
| `values` | Array   | Values corresponding, in order, to the Data columns |
| `overview`| Boolean| Represents whether or not the row is a summary or rollup of the other rows |

### Status

| key          | type    | description                                                                     |
|--------------|---------|---------------------------------------------------------------------------------|
| `requestId`  | String  | Multi-report request ID. This ID can be used to access the multi-report request status and result which is available at the /data/{requestId} endpoint |
| `resultUrl`  | Boolean | URL at which the multi-report request status and result are made available       |
| `state`      | String  | State of the request, should be set to "PENDING" for all pending requests      |
| `query`      | Object  | [Request](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#request). The original report query will be included if the `includeQueryInResponse` key is included in the request's request options |

* * *

# /data/{requestId} Endpoint

This endpoint is used when accessing data from [multi-report queries](https://docs.foursquare.com/developer/reference/mapi-data-multiple-report-id-queries).

| Endpoint          | Verb    | Body                                             | Accepts |
|-------------------|---------|--------------------------------------------------|---------|
| `/data/{requestId}`| `GET` or `POST` | [Request](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#request). Request is optional and can be included in a POST request | JSON |

## Request

| key      | type    | description                                        |
|----------|---------|----------------------------------------------------|
| `options`| Object  | [`requestOptions`](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#requestoptions) |

## Response

| key     | type    | description                                                              |
|---------|---------|--------------------------------------------------------------------------|
| `result`| Object  | [Result](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#result). A Result is returned if the request is complete. (This object has the same structure as the Result returned from the /data endpoint) |
| `status`| Object  | [Status](https://docs.foursquare.com/developer/reference/mapi-data-api-reference#status). A Status is returned if the request is incomplete. (This object has the shape as the Status returned from the /data endpoint, but only includes the status and optional query keys)