Location Sharing

Overview

Location Sharing lets you generate secure, temporary links that show a driver's live position on a map. Send the link to a customer, partner, or anyone who needs to track a delivery, service visit, or pickup — no login required.

Use cases:

• Delivery tracking — "Your driver is on the way" with a live map and ETA
• Service appointments — Real-time technician ETA for your customers
• Dispatch coordination — Share driver positions with field coordinators
• Event logistics — Fleet visibility for partners and stakeholders

How It Works

1. Create a session — Call the API with the device token, expiry, and optional details (recipient name, notes, destination)
2. Send the link — The API returns a share_url. Send it to your recipient via SMS, email, or in-app notification
3. Recipient views — They open the link in any browser and see a live map with the driver's position, speed, ETA, and your personalized message
4. Session ends — The link expires automatically, or you can complete/cancel it via the API

Creating a Share Session

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/sharing/sessions" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "1e653223-8efe-4904-baaa-23f0972924e0",
    "instance_id": "your-instance-id",
    "expires_in_hours": 4,
    "recipient_name": "Jane Doe",
    "notes": "Your package is on the way!",
    "order_id": "ORD-2024-1234",
    "destination": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "label": "123 Main Street, London"
    },
    "share_config": {
      "show_speed": true,
      "show_heading": true,
      "show_eta": true,
      "show_destination_on_map": true
    }
  }'

Response (201 Created):

{
  "id": "664a1f...",
  "share_token": "Ef0XtIPPXp",
  "share_url": "https://your-frontend.com/share/Ef0XtIPPXp",
  "links": {
    "map_url": "https://your-frontend.com/share/Ef0XtIPPXp",
    "api_url": "https://your-api.com/api/v1/share/Ef0XtIPPXp",
    "ws_url": "wss://your-api.com/api/v1/share/Ef0XtIPPXp/live"
  },
  "device_token": "1e653223-...",
  "instance_id": "your-instance-id",
  "status": "active",
  "created_at": 1776000000,
  "expires_at": 1776014400,
  "order_id": "ORD-2024-1234",
  "recipient_name": "Jane Doe",
  "destination": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "label": "123 Main Street, London"
  }
}

Send the share_url (or links.map_url) to your customer — that is the page they open in their browser.

Request Fields

Share Configuration

What the Recipient Sees

The share page is a clean, mobile-friendly live map optimized for the recipient experience:

• Driver marker — Real-time position on the map, updated automatically
• Driver details card — Current speed, heading, and last-updated time
• ETA card — Estimated arrival countdown (when destination is configured)
• Destination marker — Pin on the map showing the delivery location
• Driver name — Resolved from device metadata when available
• Recipient name and notes — Your personalized message
• Center button — One tap to recenter the map on the driver
• Connection indicator — Green dot confirming live updates are active

No login, no app download, no account creation. The recipient simply opens the link.

Sharing from the Embedded Tracker

You can also create share sessions directly from the embedded tracker map — no API calls required:

1. Click a device marker to open its popup
2. Click the "Share" button
3. Fill in the share form: recipient name, order ID, notes, expiry, destination, and visibility toggles
4. Click "Create Share Link"
5. Copy the generated link and send it to your recipient

Active sessions for the device are listed in the same panel and can be terminated with a single click.

Managing Sessions

List Sessions

curl "https://portal-apis.telematicssdk.com/realtime/api/v1/sharing/sessions?instance_id=YOUR_INSTANCE&status=active" \
  -H "Authorization: Bearer YOUR_JWT"

Filter by status, device_token, order_id, with limit and offset for pagination.

Update a Session

Change notes, configuration, or destination while a session is active:

curl -X PATCH "https://portal-apis.telematicssdk.com/realtime/api/v1/sharing/sessions/SESSION_ID?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Updated: driver will arrive from the back entrance",
    "share_config": { "show_speed": false }
  }'

Complete a Session

Mark a session as done (e.g. delivery completed):

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/sharing/sessions/SESSION_ID/complete?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT"

Cancel a Session

Remove a session immediately:

curl -X DELETE "https://portal-apis.telematicssdk.com/realtime/api/v1/sharing/sessions/SESSION_ID?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT"

Session Lifecycle

Sessions transition automatically to expired when their time limit is reached. You can also explicitly complete or cancel a session at any time.

Real-Time Updates

The share page connects via WebSocket for live position streaming:

• Endpoint: wss://{host}/api/v1/share/{share_token}/live
• Update frequency: Configurable via update_interval_seconds (default: 5 seconds)
• Reconnection: Automatic with exponential backoff (up to 5 attempts)
• Session validation: Re-checked every 30 seconds; recipients are notified immediately if the session ends

No polling, no manual refresh — the driver's marker moves on the map as they drive.

Security

• Token-based access — Share links use cryptographically random tokens. The token in the URL is the only credential needed.
• Time-limited — Every session has a configurable expiry (up to 7 days)
• Rate limiting — The public API is rate-limited to prevent abuse
• Tenant isolation — You can only manage sessions within your own instance
• Explicit termination — Complete or cancel sessions at any time to immediately revoke access

Service Limits

API Endpoint Summary

Admin endpoints require instance_id as a query parameter.