YipiiYipii IoT Docs
Getting Started

Quick Start

Common API usage examples for Yipii IoT

Share

This guide provides practical examples for common API operations. All examples assume you have already authenticated and have your access token.

Prerequisites

// Setup for all examples
const API_BASE = 'https://api.yipii.io/api';
const ACCOUNT_KEY = 'your-account-key';
const ACCESS_TOKEN = 'your-access-token';
 
const headers = {
  'Authorization': `Bearer ${ACCESS_TOKEN}`,
  'Accept': 'application/json',
  'Content-Type': 'application/json',
};

List All Assets

Fetch all assets (vehicles, equipment) in your account.

JavaScript

async function listAssets() {
  const response = await fetch(
    `${API_BASE}/${ACCOUNT_KEY}/asset`,
    { headers }
  );
 
  const data = await response.json();
  return data.data;
}
 
// Usage
const assets = await listAssets();
assets.forEach(asset => {
  console.log(`${asset.name} (${asset.registration})`);
});

cURL

curl -X GET "https://api.yipii.io/api/{account_key}/asset" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 123,
      "name": "Delivery Van 1",
      "registration": "ABC-123",
      "vin": "1HGBH41JXMN109186",
      "make": "Ford",
      "model": "Transit",
      "year": 2023,
      "tracker": {
        "id": 456,
        "imei": "123456789012345",
        "online": true,
        "last_update": "2026-02-01T10:30:00Z"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 42
  }
}

Get Asset Location

Fetch the current location of a specific asset.

JavaScript

async function getAssetLocation(assetId) {
  const response = await fetch(
    `${API_BASE}/${ACCOUNT_KEY}/asset/${assetId}/location`,
    { headers }
  );
 
  return response.json();
}
 
// Usage
const location = await getAssetLocation(123);
console.log(`Lat: ${location.latitude}, Lng: ${location.longitude}`);
console.log(`Speed: ${location.speed} km/h`);
console.log(`Last update: ${location.timestamp}`);

cURL

curl -X GET "https://api.yipii.io/api/{account_key}/asset/123/location" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "latitude": 35.8992,
  "longitude": 14.5141,
  "altitude": 45,
  "speed": 65,
  "heading": 180,
  "timestamp": "2026-02-01T10:30:00Z",
  "ignition": true,
  "odometer": 45230,
  "satellites": 12
}

Get Location History

Fetch historical positions for an asset within a date range.

JavaScript

async function getLocationHistory(assetId, startDate, endDate) {
  const params = new URLSearchParams({
    start: startDate.toISOString(),
    end: endDate.toISOString(),
  });
 
  const response = await fetch(
    `${API_BASE}/${ACCOUNT_KEY}/asset/${assetId}/history?${params}`,
    { headers }
  );
 
  return response.json();
}
 
// Usage - Last 24 hours
const now = new Date();
const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
const history = await getLocationHistory(123, yesterday, now);
 
console.log(`${history.data.length} positions in the last 24 hours`);

cURL

curl -X GET "https://api.yipii.io/api/{account_key}/asset/123/history?start=2026-02-01T00:00:00Z&end=2026-02-01T23:59:59Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Generate a Report

Request a trip report through the Reporting Service. Reports are generated asynchronously — you submit a request, then wait for completion via WebSocket or polling.

For the full async flow with WebSocket integration, see the Reporting Service guide.

JavaScript

async function generateTripReport(assetId, startDate, endDate) {
  const response = await fetch(
    'https://reporting.yipii.io/api/v1/reports/generate',
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        type: 'trip',
        asset_id: assetId,
        date_from: startDate.toISOString().split('T')[0],
        date_to: endDate.toISOString().split('T')[0],
        format: 'pdf',
      }),
    }
  );
 
  const { report_id } = await response.json();
  return report_id;
}
 
async function checkReportStatus(reportId) {
  const response = await fetch(
    `https://reporting.yipii.io/api/v1/reports/${reportId}/status`,
    { headers }
  );
 
  return response.json();
}
 
// Usage
const reportId = await generateTripReport(123, yesterday, now);
console.log(`Report queued: ${reportId}`);
 
// Poll for completion (or use WebSocket — see Reporting Service guide)
const status = await checkReportStatus(reportId);
if (status.generation_status === 'completed') {
  console.log(`Download: ${status.file_url}`);
}

cURL

# Request report
curl -X POST "https://reporting.yipii.io/api/v1/reports/generate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "trip",
    "asset_id": 123,
    "date_from": "2026-02-01",
    "date_to": "2026-02-01",
    "format": "pdf"
  }'
 
# Check status
curl -X GET "https://reporting.yipii.io/api/v1/reports/{report_id}/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Share live tracking with customers or partners.

JavaScript

async function createTrackingLink(assetId, options = {}) {
  const response = await fetch(
    `${API_BASE}/${ACCOUNT_KEY}/public-tracking-link`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        asset_id: assetId,
        name: options.name || 'Customer Tracking',
        access_type: options.accessType || 'public',
        expires_at: options.expiresAt || null,
        show_eta: options.showEta ?? true,
        show_history: options.showHistory ?? false,
      }),
    }
  );
 
  return response.json();
}
 
// Usage
const link = await createTrackingLink(123, {
  name: 'Order #12345 Delivery',
  accessType: 'public',
  showEta: true,
});
 
console.log(`Share this link: ${link.public_url}`);

cURL

curl -X POST "https://api.yipii.io/api/{account_key}/public-tracking-link" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": 123,
    "name": "Order #12345 Delivery",
    "access_type": "public",
    "show_eta": true
  }'

Response

{
  "id": 789,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Order #12345 Delivery",
  "public_url": "https://iot.yipii.io/track/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "access_type": "public",
  "show_eta": true,
  "expires_at": null
}

Real-time WebSocket Updates

Subscribe to live position updates over WebSocket. The server uses a Pusher-compatible protocol. For the full guide covering public tracking, mobile SDKs, scaling, and security, see Live Tracking & WebSocket.

JavaScript

import Pusher from 'pusher-js';
 
const pusher = new Pusher('your-app-key', {
  wsHost: 'ws.yipii.io',
  wsPort: 443,
  wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
  disableStats: true,
  cluster: '',
  authEndpoint: 'https://api.yipii.io/broadcasting/auth',
  auth: {
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
    },
  },
});
 
const channel = pusher.subscribe(`private-account.${ACCOUNT_KEY}`);
 
channel.bind('.location.updated', (data) => {
  const updates = Array.isArray(data) ? data : [data];
  updates.forEach(loc => {
    console.log(`${loc.assetName}: ${loc.latitude}, ${loc.longitude}`);
    console.log(`Speed: ${loc.speed} km/h`);
  });
});
 
// Cleanup
// pusher.disconnect();

Position Update Format

{
  "assetId": 123,
  "assetName": "Delivery Van 1",
  "latitude": 35.8992,
  "longitude": 14.5141,
  "speed": 65,
  "course": 180,
  "timestamp": 1707216000000,
  "status": {
    "name": "moving",
    "ignition": true,
    "engine": true
  }
}

Error Handling

Always handle API errors gracefully.

JavaScript

class YipiiAPIError extends Error {
  constructor(message, status, response) {
    super(message);
    this.name = 'YipiiAPIError';
    this.status = status;
    this.response = response;
  }
}
 
async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      ...headers,
      ...options.headers,
    },
  });
 
  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new YipiiAPIError(
      error.message || `HTTP ${response.status}`,
      response.status,
      error
    );
  }
 
  return response.json();
}
 
// Usage with error handling
try {
  const assets = await apiRequest(`${API_BASE}/${ACCOUNT_KEY}/asset`);
  console.log('Assets:', assets);
} catch (error) {
  if (error instanceof YipiiAPIError) {
    if (error.status === 401) {
      console.error('Token expired, please re-authenticate');
    } else if (error.status === 429) {
      console.error('Rate limited, slow down requests');
    } else {
      console.error(`API error: ${error.message}`);
    }
  } else {
    console.error('Network error:', error);
  }
}

Pagination

Handle paginated responses for large datasets.

JavaScript

async function* paginatedFetch(baseUrl) {
  let page = 1;
  let hasMore = true;
 
  while (hasMore) {
    const response = await fetch(`${baseUrl}?page=${page}`, { headers });
    const data = await response.json();
 
    yield* data.data;
 
    hasMore = page < data.meta.last_page;
    page++;
  }
}
 
// Usage
for await (const asset of paginatedFetch(`${API_BASE}/${ACCOUNT_KEY}/asset`)) {
  console.log(asset.name);
}

Next Steps

Was this page helpful?

Previous

API Keys

Next

Live Tracking & WebSocket

On this page

Quick Start | Yipii IoT Docs