Integrate Spaza Insights monitoring data directly into your systems. Enterprise customers can programmatically access detection data, analytics, and more.
The Spaza Insights API allows Enterprise customers to programmatically access monitoring data, manage their music catalog, and generate custom reports. All API requests must be authenticated using API keys.
API access is available on Enterprise plans only. Contact sales@spazainsights.com to upgrade your plan and obtain API credentials.
https://api.spazainsights.com/v1
All responses are returned in JSON format with standard HTTP status codes.
{
"data": { ... },
"meta": {
"page": 1,
"per_page": 50,
"total": 1234
}
}
All API requests require authentication using API keys. Include your API key in the request header.
API keys are generated in your Spaza Insights dashboard. Go to Settings > API to create and manage your keys.
Authorization: Bearer YOUR_API_KEY
curl -X GET "https://api.spazainsights.com/v1/detections" \
-H "Authorization: Bearer sk_live_abc123xyz" \
-H "Content-Type: application/json"
Never share your API key publicly or commit it to version control. Keep your keys secure and rotate them periodically.
The Spaza Insights API provides the following main endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | /detections |
List all detections for your catalog |
| GET | /detections/{id} |
Get a specific detection |
| GET | /tracks |
List all tracks in your catalog |
| POST | /tracks |
Add a new track for monitoring |
| PUT | /tracks/{id} |
Update track metadata |
| DELETE | /tracks/{id} |
Remove a track from monitoring |
| GET | /analytics |
Get analytics and statistics |
| GET | /reports |
Generate custom reports |
| GET | /stations |
List monitored stations |
Retrieve detection data for your monitored music.
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| per_page | integer | Items per page (default: 50, max: 100) |
| track_id | string | Filter by specific track |
| station_id | string | Filter by specific station |
| country | string | Filter by country code |
| from_date | date | Start date (ISO 8601 format) |
| to_date | date | End date (ISO 8601 format) |
{
"data": [
{
"id": "det_abc123",
"track_id": "trk_def456",
"track_title": "Song Title",
"artist_name": "Artist Name",
"station_id": "sta_ghi789",
"station_name": "Radio Station",
"country": "KE",
"detected_at": "2024-12-15T14:30:00Z",
"duration_seconds": 245,
"confidence": 0.98
}
],
"meta": {
"page": 1,
"per_page": 50,
"total": 1234
}
}
Retrieve detailed information about a specific detection.
Manage your music catalog for monitoring.
{
"title": "Song Title",
"artist": "Artist Name",
"isrc": "US-XXX-24-12345",
"album": "Album Name",
"release_date": "2024-01-15",
"duration_seconds": 245,
"audio_url": "https://example.com/audio.mp3"
}
Removes a track from monitoring. This action cannot be undone.
Retrieve analytics and statistics for your monitored content.
| Parameter | Type | Description |
|---|---|---|
| group_by | string | day, week, month, station, country |
| from_date | date | Start date |
| to_date | date | End date |
{
"data": {
"total_detections": 15420,
"unique_stations": 45,
"countries_reached": 12,
"top_tracks": [...],
"top_stations": [...],
"detections_by_day": [...],
"detections_by_country": [...]
}
}
Generate and download custom reports.
{
"type": "royalty",
"format": "pdf",
"from_date": "2024-01-01",
"to_date": "2024-12-31",
"include_charts": true,
"include_station_details": true
}
royalty - Royalty documentation reportperformance - Airplay performance summarygeographic - Geographic distribution reportstation - Station-by-station breakdowncustom - Custom report with selected metricsReceive real-time notifications when new detections occur.
{
"url": "https://your-server.com/webhook",
"events": ["detection.created"],
"active": true
}
| Event | Description |
|---|---|
detection.created |
New detection recorded |
track.added |
New track added to catalog |
track.removed |
Track removed from catalog |
report.completed |
Report generation finished |
{
"event": "detection.created",
"timestamp": "2024-12-15T14:30:00Z",
"data": {
"detection_id": "det_abc123",
"track_id": "trk_def456",
"station_id": "sta_ghi789"
}
}
The API uses standard HTTP status codes and returns error details in JSON format.
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created (resource successfully created) |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 429 | Rate Limited - Too many requests |
| 500 | Internal Server Error |
{
"error": {
"code": "invalid_parameter",
"message": "Invalid date format. Use ISO 8601.",
"details": {
"field": "from_date"
}
}
}
API requests are subject to rate limiting to ensure fair usage and system stability.
| Plan | Requests/Hour | Requests/Day |
|---|---|---|
| Enterprise | 10,000 | 100,000 |
Every API response includes the following headers:
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1702675200
Official SDKs are available for popular programming languages:
from spaza_insights import Client
client = Client(api_key="sk_live_abc123xyz")
# Get detections
detections = client.detections.list(
from_date="2024-01-01",
to_date="2024-12-31",
per_page=100
)
# Add a new track
track = client.tracks.create(
title="My Song",
artist="My Artist",
audio_url="https://example.com/song.mp3"
)
API access is available for Enterprise customers. Contact our team to get your API credentials and start integrating.