Location Update

Use this endpoint to send GPS location updates during a trip.

POST https://hub.vectorcare.com/openapi/v2.0/requests/{request_id}/locations/

Note: URLs must include the trailing slash.

Request Body

Send an array of location objects (max 200 per request):

[
  {
    "lat": 37.8577747,
    "lng": -122.49209,
    "alt": 20.23,
    "speed": 10.3,
    "timestamp": 1575497090.131
  },
  {
    "lat": 37.8578123,
    "lng": -122.49198,
    "alt": 20.45,
    "speed": 12.1,
    "timestamp": 1575497095.456
  }
]

Field	Type	Description
`lat`	number	Latitude
`lng`	number	Longitude
`alt`	number	Altitude in meters
`speed`	number	Speed (optional)
`timestamp`	number	Unix epoch timestamp in seconds

Example Request

curl -X POST "https://hub.vectorcare.com/openapi/v2.0/requests/KP-ABCD1234/locations/" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '[
    {
      "lat": 37.8577747,
      "lng": -122.49209,
      "alt": 20.23,
      "speed": 10.3,
      "timestamp": 1575497090.131
    }
  ]'

Responses

Success (200 OK)

{}

An empty object indicates success.

Missing Required Fields (400 Bad Request)

[
  {
    "timestamp": [
      {
        "message": "This field is required.",
        "code": "common:required"
      }
    ],
    "lat": [
      {
        "message": "This field is required.",
        "code": "common:required"
      }
    ],
    "lng": [
      {
        "message": "This field is required.",
        "code": "common:required"
      }
    ],
    "alt": [
      {
        "message": "This field is required.",
        "code": "common:required"
      }
    ]
  }
]

Batching Locations

You can send up to 200 location objects in a single request. This is useful for:

Sending historical location data
Batch uploading after connectivity issues
Reducing API call frequency

[
  {"lat": 37.857, "lng": -122.492, "alt": 20, "timestamp": 1575497090.0},
  {"lat": 37.858, "lng": -122.491, "alt": 21, "timestamp": 1575497095.0},
  {"lat": 37.859, "lng": -122.490, "alt": 22, "timestamp": 1575497100.0}
  // ... up to 200 total
]

Timestamp Format

The timestamp is a Unix epoch timestamp in seconds as a floating-point number:

1575497090.131
│         │
│         └── Milliseconds (optional)
└──────────── Seconds since Jan 1, 1970 UTC

Convert from ISO 8601 to Unix timestamp in your language of choice.

Best Practices

Send locations periodically

During active transport, send locations every 10-30 seconds
Batch multiple points if your system collects them faster

Handle offline scenarios

If connectivity is lost:

Store locations locally
Batch upload when connectivity returns
Ensure timestamps reflect when locations were recorded, not uploaded

Validate before sending

Ensure coordinates are valid (lat: -90 to 90, lng: -180 to 180)
Verify altitude is reasonable for your region
Confirm timestamps are not in the future