Heads Up Zimbabwe Data API
Real-time, community-verified safety incident data for Zimbabwe. Built for security companies, insurers, fleet operators, and developers.
Request API accessWhat you get
- Live incident feed updated in real time as community reports come in
- 309+ verified incidents across 29 cities and growing
- Structured data: category, coordinates, city, description, confidence level, source
- Filter by city, category, date range, or proximity radius
- GeoJSON format for direct map integration
- Standard REST API, works with any language or platform
Who uses it
- Security companies — enrich client reports with live local data
- Insurance — risk scoring by location for policy underwriting
- Fleet operators — route safety checks before dispatch
- Property developers — neighbourhood safety profiling
- Journalists & researchers — structured crime data for analysis
Authentication
All API requests require a Bearer token in the Authorization header. Contact us to get your key.
curl https://headsup.cloutconnect.co.zw/api/v1/incidents \
-H "Authorization: Bearer YOUR_API_KEY"Endpoints
/api/v1/incidentsReturns active safety incidents. Supports filtering and pagination.
| Parameter | Type | Description |
|---|---|---|
| city | string | Filter by city name (e.g. Harare) |
| category | string | robbery, mugging, scam, unsafe_area, road_hazard, accident_zone, dangerous_route, other |
| since | ISO date | Only incidents after this date. Default: last 30 days |
| lat, lng | decimal | Center point for radius filter |
| radius_km | number | Filter to incidents within N km. Default: 5 |
| limit | number | Max results. Default: 100, max: 500 |
| format | string | json (default) or geojson |
Example response
{
"incidents": [
{
"id": 142,
"lat": -17.8292,
"lng": 31.0522,
"city": "Harare",
"category": "robbery",
"description": "Armed robbery at High Glen Road...",
"confirmationCount": 17,
"sourceLabel": "Safeguard Security Feb 2026",
"occurredAt": "2026-02-15T19:00:00.000Z"
}
],
"meta": {
"total": 1,
"since": "2026-01-01T00:00:00.000Z",
"generated": "2026-04-19T08:00:00.000Z"
}
}Rate limits
Rate limits are enforced per API key, per hour. Every response includes headers so you can track your usage programmatically.
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Requests remaining before you are throttled |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
Retry-After | Seconds to wait before retrying (only on 429 responses) |
When you exceed your limit the API returns 429 Too Many Requests. Implement exponential backoff and check Retry-After before retrying.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746000000
Retry-After: 3412
{ "error": "Rate limit exceeded. Max 1000 requests per hour per API key." }Webhooks
Business and Enterprise plans include webhook support. Instead of polling the API, register an HTTPS endpoint and receive a signed POST request within seconds of each new incident being published.
your-endpoint.com/webhookDelivered by Heads Up within seconds of a new incident. Signed with HMAC-SHA256.
Each request includes an X-HU-Signature header — HMAC-SHA256 of the raw request body using your webhook secret. Always verify this before processing.
// Node.js verification example
const crypto = require('crypto')
function verify(secret, rawBody, signature) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
)
}Webhook payload matches the standard incident object:
{
"event": "incident.created",
"incident": {
"id": 142,
"lat": -17.8292,
"lng": 31.0522,
"city": "Harare",
"category": "robbery",
"description": "Armed robbery at High Glen Road...",
"confirmationCount": 0,
"sourceLabel": null,
"occurredAt": "2026-02-15T19:00:00.000Z"
}
}Webhooks that fail 5 consecutive deliveries are automatically paused. You can resume them from your admin panel. Each delivery attempt has an 8-second timeout.
Pricing
All plans include access to the full incident dataset. Pricing is in USD and billed monthly. We work with organisations of all sizes — if none of these fit, get in touch.
- 1,000 requests / day
- 30-day incident history
- All cities and categories
- Email support
- 10,000 requests / day
- Full incident history
- GeoJSON format
- Webhook support
- Priority support
- Unlimited requests
- Real-time webhooks
- Custom data fields
- Dedicated support
- SLA guarantee
Request access
Fill in the form below and we will set up your key within 24 hours.