Overview
All requests and responses use JSON. Include the header:
Content-Type: application/json
No authentication is required for any endpoint.
Endpoints
POST
/api/location
Push GPS data from IoT device
Receives latitude/longitude data from an IoT device and stores it in the database.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
deviceId | string | Required | Unique identifier of the IoT device |
latitude | number | Required | Latitude in decimal degrees (−90 to 90) |
longitude | number | Required | Longitude in decimal degrees (−180 to 180) |
altitude | number | Optional | Altitude in metres above sea level |
speed | number | Optional | Speed in km/h |
timestamp | ISO string | Optional | Device time — defaults to server time if omitted |
Example Request
POST https://api.blackbucktechnology.com/api/location
{
"deviceId" : "DEVICE_001",
"latitude" : 18.5204,
"longitude" : 73.8567,
"altitude" : 560.0,
"speed" : 40.5,
"timestamp" : "2026-03-04T10:00:00Z"
}
Response
201 Created
400 Bad Request
{
"success" : true,
"message" : "Location saved successfully.",
"data": {
"_id" : "65f1a2b3c4d5e6f7a8b9c0d1",
"deviceId" : "DEVICE_001",
"latitude" : 18.5204,
"longitude" : 73.8567,
"altitude" : 560.0,
"speed" : 40.5,
"timestamp" : "2026-03-04T10:00:00.000Z",
"createdAt" : "2026-03-04T10:00:01.123Z"
}
}
GET
/api/location/:deviceId
Fetch location history for a device
Returns the latest location records for a given device, sorted by most recent first.
Path Parameter
| Parameter | Type | Description |
|---|---|---|
deviceId | string | The device identifier used when pushing data |
Query Parameter
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Number of records to return (max suggested: 100) |
Example Request
GET https://api.blackbucktechnology.com/api/location/DEVICE_001?limit=5
Response
200 OK
{
"success" : true,
"count" : 2,
"data": [
{
"_id" : "65f1a2b3c4d5e6f7a8b9c0d1",
"deviceId" : "DEVICE_001",
"latitude" : 18.5204,
"longitude" : 73.8567,
"altitude" : 560.0,
"speed" : 40.5,
"timestamp" : "2026-03-04T10:00:00.000Z"
},
{ "..." : "..." }
]
}
GET
/health
Server health check
Returns server status. Use this to verify the API is reachable.
Example Request
GET https://api.blackbucktechnology.com/health
Response — 200 OK
{
"status" : "ok",
"time" : "2026-03-04T10:00:00.000Z"
}
Error Codes
| Status | Meaning |
|---|---|
| 201 | Record created successfully |
| 200 | Request successful |
| 400 | Missing required fields (deviceId, latitude, or longitude) |
| 500 | Internal server error — check server logs |
Quick Test (curl)
Push a location
curl -X POST https://api.blackbucktechnology.com/api/location \
-H "Content-Type: application/json" \
-d '{
"deviceId" : "DEVICE_001",
"latitude" : 18.5204,
"longitude" : 73.8567,
"speed" : 40.5
}'
Fetch latest 5 records
curl https://api.blackbucktechnology.com/api/location/DEVICE_001?limit=5