YipiiYipii IoT Docs
Getting Started

Quick Start

The Yipii IoT API in one page: list assets, read a position, pull history, generate a report and open a tracking link — with a runnable example each.

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