Reference Data API

These endpoints expose the lookup tables that drive the rest of the platform: the tracker models you can fit, the fuel prices used in fuel cost calculations, the toll gates on your corridors, and the localisation payload the mobile apps read at startup.

These resources are read-only. Contact Livepin to have reference data added or changed.

All endpoints require the standard credentials:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer $JWT_TOKEN

GPS models

The catalogue of supported tracker hardware. credit_usage tells you how many credits a device on that model consumes, and is_dashcam marks camera-capable units.

Name
GET /api/gps-models
Description
List GPS models.
Name
GET /api/gps-models/:id
Description
Get one GPS model.

Model fields

Name
model_name
Type
string
Description
Model name, for example MC 401.
Name
company
Type
string
Description
Manufacturer, for example MettaX.
Name
device_image
Type
media
Description
Product image.
Name
max_battery_voltage
Type
decimal
Description
Defaults to 5.
Name
credit_usage
Type
integer
Description
Credits consumed per active device.
Name
is_dashcam
Type
boolean
Description
Camera capable. Defaults to false.

List GPS models

curl "$LIVEPIN_API_BASE_URL/api/gps-models" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

{
  "data": [
    {
      "id": 17,
      "attributes": {
        "model_name": "MC 401",
        "company": "MettaX",
        "max_battery_voltage": "5",
        "credit_usage": 5,
        "is_dashcam": true
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 } }
}

A device is linked to a model through gps_model. To list the devices of a model, use GET /api/devices/by-gps-model/:gps_model_id.

Fuel prices

State-level diesel and petrol prices. These feed the fuel cost columns in the fuel reports.

Name
GET /api/fuel-prices
Description
List fuel prices.
Name
GET /api/fuel-prices/:id
Description
Get one entry.

Entry fields

Name
stateName
Type
string
Description
State or region name.
Name
stateCode
Type
string
Description
State code.
Name
country
Type
string
Description
Country name.
Name
dieselPerLitrePrice
Type
decimal
Description
Diesel price per litre.
Name
petrolPerLitrePrice
Type
decimal
Description
Petrol price per litre.

List fuel prices

curl -G "$LIVEPIN_API_BASE_URL/api/fuel-prices" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d "filters[stateCode][\$eq]=MH"

Response (trimmed)

{
  "data": [
    {
      "id": 14,
      "attributes": {
        "stateName": "Maharashtra",
        "stateCode": "MH",
        "country": "India",
        "dieselPerLitrePrice": "92.15",
        "petrolPerLitrePrice": "104.21"
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 } }
}

Toll gates

Reference metadata for toll plazas, including the operating company and the FASTag bank, so you can attribute toll spend on operated corridors.

Name
GET /api/toll-gates
Description
List toll gates. Returns a flat array with location populated.
Name
GET /api/toll-gates/:id
Description
Get one toll gate.

Gate fields

Name
gate_code
Type
string
Description
Required, unique. Plaza code.
Name
name
Type
string
Description
Plaza name.
Name
gate_type
Type
string
Description
Plaza type.
Name
operating_company
Type
string
Description
Concessionaire.
Name
fastag_bank_name
Type
string
Description
FASTag acquiring bank.
Name
location
Type
object
Description
Location component: latitude, longitude, address.

List toll gates

curl "$LIVEPIN_API_BASE_URL/api/toll-gates" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

[
  {
    "id": 6,
    "gate_code": "TG-0421",
    "name": "Example Toll Plaza",
    "gate_type": "HIGHWAY",
    "operating_company": "Example Infra Ltd",
    "fastag_bank_name": "Example Bank",
    "location": {
      "latitude": "13.1989",
      "longitude": "77.7068",
      "address": "NH 44, Karnataka"
    }
  }
]

Geofences

Geofences define areas used by the geofence reports and geofence_enter / geofence_exit notifications. A geofence can be attached to a vehicle group.

Name
GET /api/geofences
Description
List geofences.
Name
GET /api/geofences/:id
Description
Get one geofence.
Name
POST /api/geofences
Description
Create a geofence.
Name
PUT /api/geofences/:id
Description
Update a geofence.
Name
DELETE /api/geofences/:id
Description
Delete a geofence.

Create geofence

curl -X POST "$LIVEPIN_API_BASE_URL/api/geofences" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Warehouse",
      "coordinates": [[80.1, 13.2], [80.2, 13.2], [80.2, 13.3]]
    }
  }'

Attach geofence to a group

curl -X POST "$LIVEPIN_API_BASE_URL/api/vehicle-groups" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mumbai Fleet","vehicles":[3001,3002],"geofences":[6]}'

Routes

Named routes let you compare actual driving against a planned corridor and produce route deviation alerts.

Name
GET /api/routes
Description
List routes.
Name
GET /api/routes/:id
Description
Get one route.
Name
POST /api/routes
Description
Create a route.
Name
PUT /api/routes/:id
Description
Update a route.
Name
DELETE /api/routes/:id
Description
Delete a route.
Name
POST /api/routes/snap-to-road
Description
Snap a loose coordinate list onto the road network.
Name
GET /api/vehicles/:id/list-linked-routes
Description
Routes linked to a vehicle.
Name
POST /api/vehicles/:id/link-route
Description
Link routes to a vehicle.
Name
POST /api/vehicles/:id/unlink-route
Description
Unlink routes from a vehicle.

Snap to road

POST

/api/routes/snap-to-road

curl -X POST "$LIVEPIN_API_BASE_URL/api/routes/snap-to-road" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"coordinates":[{"lat":13.1269,"lng":80.2074},{"lat":13.129,"lng":80.209}]}'

Link routes

POST

/api/vehicles/:id/link-route

curl -X POST "$LIVEPIN_API_BASE_URL/api/vehicles/3001/link-route" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"route_ids":[5,6,7]}'

Localisation

Remote copy for the mobile apps. This is a single-type resource, so it has no ID.

Name
GET /api/localisation
Description
Read the localisation payload, including plans_info.

Read localisation

curl "$LIVEPIN_API_BASE_URL/api/localisation" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

{
  "data": {
    "id": 1,
    "attributes": {
      "plans_info": {
        "trial_months": 2,
        "currency": "INR"
      }
    }
  },
  "meta": {}
}

Continue to Storefront API