127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
# Activities API Documentation
|
|
|
|
## Overview
|
|
The Activities API provides event tracking data for short URLs. It allows retrieving visitor activity information based on various filters such as URL slug, domain, and date ranges.
|
|
|
|
## Endpoint
|
|
```
|
|
GET /api/activities
|
|
```
|
|
|
|
## Request Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|------------|---------|----------|-------------|
|
|
| `slug` | string | No* | The short URL slug to filter events by |
|
|
| `domain` | string | No* | The domain to filter events by |
|
|
| `startTime`| string | No* | Start time for date range filter (ISO format) |
|
|
| `endTime` | string | No* | End time for date range filter (ISO format) |
|
|
| `page` | integer | No | Page number for pagination (default: 1) |
|
|
| `pageSize` | integer | No | Number of records per page (default: 50) |
|
|
| `format` | string | No | Response format, set to 'csv' for CSV output (default: JSON) |
|
|
|
|
\* Either `slug`+`domain` combination OR at least one of `startTime`/`endTime` must be provided.
|
|
|
|
## Response Formats
|
|
|
|
### JSON Format (Default)
|
|
JSON responses include the following structure:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": "event-id",
|
|
"type": "event-type",
|
|
"time": "timestamp",
|
|
"visitor": {
|
|
"id": "visitor-id",
|
|
"ipAddress": "ip-address",
|
|
"userAgent": "user-agent-string",
|
|
"referrer": "referrer-url"
|
|
},
|
|
"device": {
|
|
"type": "device-type",
|
|
"browser": "browser-name",
|
|
"os": "operating-system"
|
|
},
|
|
"location": {
|
|
"country": "country-code",
|
|
"city": "city-name"
|
|
},
|
|
"link": {
|
|
"id": "link-id",
|
|
"slug": "link-slug",
|
|
"originalUrl": "original-url",
|
|
"label": "link-label",
|
|
"tags": ["tag1", "tag2"]
|
|
},
|
|
"utm": {
|
|
"source": "utm-source",
|
|
"medium": "utm-medium",
|
|
"campaign": "utm-campaign",
|
|
"term": "utm-term",
|
|
"content": "utm-content"
|
|
}
|
|
}
|
|
],
|
|
"meta": {
|
|
"total": 100,
|
|
"page": 1,
|
|
"pageSize": 50
|
|
}
|
|
}
|
|
```
|
|
|
|
In case of an error:
|
|
```json
|
|
{
|
|
"success": false,
|
|
"data": null,
|
|
"error": "Error message description"
|
|
}
|
|
```
|
|
|
|
### CSV Format
|
|
When `format=csv` is specified, the response is returned as plain text in CSV format with the following columns:
|
|
- `time`: Timestamp of the event
|
|
- `activity`: Type of activity/event
|
|
- `campaign`: UTM campaign value (defaults to "demo" if not found)
|
|
- `clientId`: Visitor ID
|
|
- `originPath`: Original request path or referrer URL
|
|
|
|
## Examples
|
|
|
|
### Get activities for a specific short URL
|
|
```
|
|
GET /api/activities?slug=promo123&domain=googleads.link
|
|
```
|
|
|
|
### Get activities within a date range
|
|
```
|
|
GET /api/activities?startTime=2023-06-01T00:00:00Z&endTime=2023-06-30T23:59:59Z
|
|
```
|
|
|
|
### Get events as CSV
|
|
```
|
|
GET /api/activities?slug=promo123&domain=googleads.link&format=csv
|
|
```
|
|
|
|
### Pagination example
|
|
```
|
|
GET /api/activities?slug=promo123&domain=googleads.link&page=2&pageSize=20
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
| Status Code | Description |
|
|
|-------------|-------------|
|
|
| 400 | Missing required parameters |
|
|
| 500 | Server error while processing the request |
|
|
|
|
## Notes
|
|
- For privacy and security reasons, some fields may be omitted or anonymized based on user settings.
|
|
- The CSV format is optimized for easy import into spreadsheet applications.
|
|
- When using the CSV format, the response is returned as plain text rather than a downloadable file.
|