Source: https://datafa.st/docs/api/website/analytics/realtime-map
Markdown source: https://datafa.st/docs/api/website/analytics/realtime-map.md
Description: Return active visitors with location and device data, plus recent goal events and payments for the [realtime map](/changelog/real-time-map). Each visitor may include conversion prediction scores when enough revenue attribution data exists.

# Get realtime map

`GET https://datafa.st/api/v1/analytics/realtime/map`

Return active visitors with location and device data, plus recent goal events and payments for the [realtime map](/changelog/real-time-map). Each visitor may include conversion prediction scores when enough revenue attribution data exists.

Active visitors are those with pageview activity in the last 10 minutes. Customers receive a prediction score of 100.

> **Related:** [Realtime map](/changelog/real-time-map) · [Mobile app](/docs/mobile-app) · [Revenue prediction](/changelog/revenue-prediction)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data.count` | number | Number of currently active visitors in the realtime window. |
| `data.visitors` | object[] | Number of unique visitors represented by this row or time bucket. Use it to compare traffic volume across dates, pages, sources, countries, devices, or campaigns. Active visitor records used to draw the realtime map/list. |
| `data.visitors[].visitorId` | string | Alias for `datafast_visitor_id` on endpoints that accept both names. |
| `data.visitors[].location` | object | Location used to place the visitor on the map. |
| `data.visitors[].location.city` | string\|null | Visitor city. |
| `data.visitors[].location.region` | string\|null | Visitor region or state. |
| `data.visitors[].location.countryCode` | string\|null | Two-letter country code. |
| `data.visitors[].system` | object | Browser, OS, and device values for the active visitor. |
| `data.visitors[].system.browser` | object\|null | Browser details object, or `null`. |
| `data.visitors[].system.browser.name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. Browser name when browser details are available. |
| `data.visitors[].system.os` | object\|null | Operating-system details object, or `null`. |
| `data.visitors[].system.os.name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data.visitors[].system.device` | object\|null | Device details object, or `null`. |
| `data.visitors[].system.device.type` | string | Device type when available. |
| `data.visitors[].currentUrl` | string\|null | Latest page URL seen for the visitor. Use it to understand where the visitor was last active before you inspect the full visitor profile. |
| `data.visitors[].referrer` | string\|null | Current referrer. |
| `data.visitors[].sessionStartTime` | string\|null | Current session start timestamp. |
| `data.visitors[].visitCount` | number | Visitor session count. |
| `data.visitors[].params` | object | First-session `ref`, `source`, `via`, and UTM parameters. Missing values are `null`. |
| `data.visitors[].latitude` | number\|null | Map latitude. |
| `data.visitors[].longitude` | number\|null | Map longitude. |
| `data.visitors[].isCustomer` | boolean | Whether payment/customer data was found for the visitor. |
| `data.visitors[].customerName` | string\|null | Customer name when available. |
| `data.visitors[].customerEmail` | string\|null | Customer email when available. |
| `data.visitors[].profileData` | object | Identify profile display data. |
| `data.visitors[].profileData.displayName` | string\|null | Identify name or customer name used by the realtime UI. |
| `data.visitors[].profileData.userId` | string\|null | User ID from Identify when available. |
| `data.visitors[].profileData.profileImage` | string (optional) | Profile image from Identify metadata when available. |
| `data.visitors[].profileData.hasProfile` | boolean | Whether an Identify profile exists. |
| `data.visitors[].profileData.isRandomName` | boolean | Whether the UI must generate a fallback display name. |
| `data.visitors[].conversionLikelihood` | object (optional) | Prediction score and raw values when conversion metrics are available. Omitted otherwise. |
| `data.visitors[].conversionLikelihood.score` | number | 0–100 conversion score. Existing customers receive `100`. |
| `data.visitors[].conversionLikelihood.confidence` | number | Prediction confidence. |
| `data.visitors[].conversionLikelihood.isCustomer` | boolean (optional) | Present and `true` for existing customers. |
| `data.visitors[].conversionLikelihood.isBaseline` | boolean (optional) | Whether the prediction uses the baseline model. |
| `data.visitors[].conversionLikelihood.dimensionMatches` | object[] (optional) | Matched prediction dimensions. |
| `data.visitors[].conversionLikelihood.raw` | object (optional) | Raw `conversionRate`, `averageValue`, and `expectedValue` values. |
| `data.conversionMetrics` | object (optional) | Baseline conversion metrics used for predictions. Present only when predictions are available. |
| `data.conversionMetrics.baselineConversionRate` | number | Baseline conversion rate. |
| `data.conversionMetrics.baselineAverageValue` | number | Baseline average customer value. |
| `data.hasConversionPredictions` | boolean | Whether prediction fields are available. |
| `data.recentEvents` | object[] | Recent goal/custom events shown in realtime UI. |
| `data.recentEvents[]._id` | string | Event ID. |
| `data.recentEvents[].type` | string\|null | Event type. |
| `data.recentEvents[].visitorId` | string | Alias for `datafast_visitor_id` on endpoints that accept both names. |
| `data.recentEvents[].timestamp` | string | Event timestamp. Use it when recording historical events; defaults to the request time. |
| `data.recentEvents[].path` | string\|null | Event page path. |
| `data.recentEvents[].countryCode` | string\|null | Event country code. |
| `data.recentEvents[].extraData` | object | Parsed event metadata. |
| `data.recentEvents[].referrer` | string\|null | Event referrer. |
| `data.recentEvents[].customerName` | string\|null | Customer name when available. |
| `data.recentEvents[].amount` | number\|null | Payment amount sent by your payment system. DataFast converts it for reporting when needed. |
| `data.recentEvents[].displayName` | string\|null | Profile or customer display name. |
| `data.recentPayments` | object[] | Recent payment events shown in realtime UI. |
| `data.recentPayments[]._id` | string | Payment ObjectId. |
| `data.recentPayments[].type` | string | Always `payment_received` for these rows. |
| `data.recentPayments[].timestamp` | string | Event timestamp. Use it when recording historical events; defaults to the request time. |
| `data.recentPayments[].name` | string\|null | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data.recentPayments[].email` | string\|null | Customer email. |
| `data.recentPayments[].amount` | number | Payment amount sent by your payment system. DataFast converts it for reporting when needed. |
| `data.recentPayments[].currency` | string | Currency code for money values, such as `USD` or `EUR`. |
| `data.recentPayments[].renewal` | boolean | Whether the payment is a recurring renewal. This affects lifecycle and renewal revenue reporting. |
| `data.recentPayments[].displayName` | null | Currently always `null` for processed payment rows. |
| `data.recentPayments[].isNew` | boolean | Currently `false`. |
| `data.recentPayments[].visible` | boolean | Currently `true`. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `analytics:read` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**404** — Website not found.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/analytics/realtime/map" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": {
    "count": 2,
    "visitors": [{
      "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
      "location": {
        "city": "Paris",
        "countryCode": "FR"
      },
      "system": {
        "browser": { "name": "Chrome" },
        "os": { "name": "Mac OS" },
        "device": { "type": "desktop" }
      },
      "currentUrl": "/pricing",
      "referrer": "Google",
      "sessionStartTime": "2026-05-21T11:55:00.000Z",
      "visitCount": 2,
      "params": { "utm_source": "google" },
      "latitude": 48.8566,
      "longitude": 2.3522,
      "isCustomer": false,
      "customerName": null,
      "customerEmail": null,
      "profileData": {
        "displayName": null,
        "userId": null,
        "hasProfile": false,
        "isRandomName": true
      }
    }],
    "hasConversionPredictions": false,
    "recentEvents": [],
    "recentPayments": []
  }
}
```