Locations

Location data is the foundation of the Bookovia Telematics API, enabling precise vehicle tracking, route optimization, and comprehensive journey analysis. This guide covers everything you need to know about working with GPS coordinates, location points, and route data.

What is Location Data?

Location data in Bookovia consists of GPS coordinates and associated telemetry information that tracks vehicle movement throughout a trip. Each location point captures:

Geographic Position - Latitude and longitude coordinates
Temporal Information - Precise timestamp when the location was recorded
Motion Data - Speed, heading, and acceleration
Quality Metrics - GPS accuracy and signal strength
Context Information - Trip association and metadata

Location Point Structure

Core Properties

Each location point contains essential positioning and motion data:

{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "timestamp": "2024-04-13T10:30:00Z",
  "speed": 35.5,
  "heading": 180.0,
  "accuracy": 5.0,
  "altitude": 10.2
}

Data Validation

Location data undergoes automatic validation to ensure quality:

Coordinate Range: Latitude (-90 to 90), Longitude (-180 to 180)
Speed Limits: Reasonable speed values (0 to 500 km/h)
Timestamp Format: ISO 8601 UTC timestamps
Accuracy Filtering: GPS points with accuracy > 100m are flagged
Duplicate Detection: Consecutive identical coordinates are filtered

Location Upload Methods

Single Location Upload

For real-time tracking applications:

curl -X POST https://api.bookovia.com/v1/locations/single-upload \
  -H "X-API-Key: bkv_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trip_id": "trip_123",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timestamp": "2024-04-13T10:30:00Z",
    "speed": 35,
    "heading": 180,
    "accuracy": 5
  }'

Batch Location Upload

For efficient bulk data transmission:

curl -X POST https://api.bookovia.com/v1/locations/batch-upload \
  -H "X-API-Key: bkv_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trip_id": "trip_123",
    "locations": [
      {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "timestamp": "2024-04-13T10:30:00Z",
        "speed": 35,
        "heading": 180
      },
      {
        "latitude": 40.7130,
        "longitude": -74.0058,
        "timestamp": "2024-04-13T10:30:30Z",
        "speed": 42,
        "heading": 175
      }
    ]
  }'

Route Generation

Automatic Route Creation

Bookovia automatically generates routes from location data:

Route Smoothing - Removes GPS noise and outliers
Road Snapping - Aligns points to actual road network
Waypoint Generation - Creates logical navigation points
Distance Calculation - Accurate route distance measurement
Time Analysis - Duration and speed calculations

Route Data Structure

{
  "trip_id": "trip_123",
  "route": {
    "coordinates": [
      [-74.0060, 40.7128],
      [-74.0058, 40.7130],
      [-74.0055, 40.7132]
    ],
    "distance_km": 12.5,
    "duration_minutes": 45,
    "waypoints": [
      {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "name": "Start Point",
        "timestamp": "2024-04-13T10:30:00Z"
      },
      {
        "latitude": 40.7150,
        "longitude": -74.0040,
        "name": "Waypoint 1",
        "timestamp": "2024-04-13T10:45:00Z"
      }
    ],
    "bounding_box": {
      "southwest": {
        "latitude": 40.7120,
        "longitude": -74.0070
      },
      "northeast": {
        "latitude": 40.7160,
        "longitude": -74.0030
      }
    }
  }
}

Geofencing

Creating Geofences

Define geographic boundaries for location-based triggers:

const geofence = await client.locations.createGeofence({
  name: 'Delivery Zone Alpha',
  type: 'circle',
  center: {
    latitude: 40.7128,
    longitude: -74.0060
  },
  radius: 500, // meters
  triggers: ['entry', 'exit']
});

Geofence Types

Type	Description	Parameters
Circle	Circular boundary	Center point + radius
Polygon	Custom shape	Array of coordinate points
Rectangle	Rectangular area	Southwest + Northeast corners

Geofence Events

Automatic events triggered when vehicles cross boundaries:

{
  "event_type": "geofence_entry",
  "geofence_id": "geofence_456",
  "trip_id": "trip_123",
  "timestamp": "2024-04-13T10:45:00Z",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "vehicle_id": "vehicle_789"
}

Location Analytics

Speed Analysis

Comprehensive speed metrics from location data:

Average Speed - Overall trip speed excluding stops
Maximum Speed - Highest recorded speed
Speed Distribution - Time spent in different speed ranges
Acceleration Patterns - Harsh acceleration/deceleration detection

Stop Detection

Automatic identification of vehicle stops:

{
  "stops": [
    {
      "start_time": "2024-04-13T10:45:00Z",
      "end_time": "2024-04-13T11:00:00Z",
      "duration_minutes": 15,
      "location": {
        "latitude": 40.7150,
        "longitude": -74.0040
      },
      "address": "123 Main St, New York, NY",
      "stop_type": "delivery"
    }
  ]
}

Idle Time Calculation

Detection and analysis of vehicle idle periods:

Engine On + Speed Zero - True idle time detection
Excessive Idling - Idle periods exceeding thresholds
Fuel Consumption - Estimated fuel waste during idle
Environmental Impact - CO2 emissions from idling

Address Resolution

Forward Geocoding

Convert addresses to coordinates:

const coordinates = await client.locations.geocode({
  address: '1600 Amphitheatre Parkway, Mountain View, CA'
});

// Returns: { latitude: 37.4224764, longitude: -122.0842499 }

Reverse Geocoding

Convert coordinates to human-readable addresses:

const address = await client.locations.reverseGeocode({
  latitude: 37.4224764,
  longitude: -122.0842499
});

// Returns: "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"

Nearby Services

Points of Interest

Find nearby locations and services:

const nearbyServices = await client.locations.findNearby({
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 1000, // meters
  categories: ['gas_station', 'restaurant', 'parking']
});

Response includes:

{
  "locations": [
    {
      "name": "Shell Gas Station",
      "category": "gas_station",
      "distance_meters": 150,
      "location": {
        "latitude": 40.7130,
        "longitude": -74.0058
      },
      "address": "456 Broadway, New York, NY",
      "rating": 4.2,
      "amenities": ["24_hour", "car_wash", "convenience_store"]
    }
  ]
}

Data Quality Management

Quality Metrics

Bookovia automatically calculates location data quality:

GPS Accuracy - Horizontal position uncertainty
Signal Strength - Satellite reception quality
Update Frequency - Time between location points
Route Continuity - Logical movement patterns

Data Filtering

Automatic filtering improves data quality:

{
  "filters_applied": {
    "accuracy_filter": {
      "threshold_meters": 50,
      "points_filtered": 12
    },
    "speed_filter": {
      "max_speed_kmh": 200,
      "points_filtered": 3
    },
    "duplicate_filter": {
      "points_filtered": 8
    }
  }
}

Quality Indicators

Each location point includes quality metrics:

{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "quality": {
    "accuracy_meters": 5.2,
    "satellite_count": 8,
    "signal_strength": "strong",
    "quality_score": 0.95
  }
}

Privacy and Security

Data Privacy

Location data is handled with strict privacy controls:

Organization Isolation - Data scoped to your organization
Access Controls - API key-based permissions
Data Retention - Configurable retention periods
Anonymization - Optional coordinate fuzzing for privacy

Security Measures

Comprehensive security for location data:

Encryption in Transit - TLS 1.3 for all API calls
Encryption at Rest - AES-256 database encryption
Access Logging - Complete audit trail
Rate Limiting - Protection against abuse

Best Practices

Upload Optimization

Batch Size Optimization

Upload 10-100 location points per batch
Avoid batches larger than 1000 points
Use compression for large payloads
Implement exponential backoff for retries

Update Frequency

30-second intervals for normal tracking
10-second intervals for high-precision needs
60-second intervals for battery conservation
Dynamic frequency based on movement detection

Data Quality

Filter points with accuracy > 50 meters
Validate coordinates before upload
Remove duplicate consecutive points
Handle GPS signal loss gracefully

Performance Tips

Network Efficiency

Compress location data payloads
Cache geocoding results locally
Use batch uploads for efficiency
Implement offline storage for poor connectivity

Battery Optimization

Adjust GPS precision based on needs
Use significant location changes (iOS/Android)
Implement smart wake-up algorithms
Balance accuracy vs. battery life

Troubleshooting

Common Issues

GPS Accuracy Problems

Symptoms: Inaccurate or erratic location pointsSolutions:

Check GPS accuracy values in uploaded data
Filter out points with accuracy > 50 meters
Ensure device has clear sky view
Consider using network-assisted GPS

Missing Location Data

Symptoms: Gaps in route or missing location pointsSolutions:

Verify API upload success (check response codes)
Implement offline storage for poor connectivity
Check device location permissions
Validate timestamp formats (ISO 8601)

Route Generation Issues

Symptoms: Incorrect or missing routesSolutions:

Ensure adequate location point density
Check for large time gaps between points
Verify coordinate accuracy and validity
Review trip start/stop locations

Use Cases

Fleet Tracking

// Real-time fleet monitoring
const fleetLocations = await client.locations.getFleetLocations({
  organization_id: 'org_123',
  include_inactive: false
});

// Display vehicles on map
fleetLocations.vehicles.forEach(vehicle => {
  map.addMarker({
    position: vehicle.last_location,
    title: vehicle.vehicle_id,
    status: vehicle.trip_status
  });
});

Delivery Optimization

// Route optimization for deliveries
const optimizedRoute = await client.locations.optimizeRoute({
  start_location: warehouse,
  destinations: deliveryAddresses,
  vehicle_constraints: {
    max_distance_km: 200,
    max_duration_hours: 8
  },
  optimization_goal: 'minimize_time'
});

Safety Monitoring

// Monitor for unsafe driving patterns
const safetyAlerts = await client.locations.analyzeSafety({
  trip_id: 'trip_123',
  checks: ['harsh_acceleration', 'sharp_turns', 'speeding'],
  thresholds: {
    acceleration_threshold: 3.5, // m/s²
    speed_limit_buffer: 10 // km/h over limit
  }
});

Integration Examples

Mobile App Integration

// React Native location tracking
import { useLocationTracking } from '@bookovia/react-native-sdk';

const LocationTracker = ({ tripId }) => {
  const { startTracking, stopTracking, currentLocation } = useLocationTracking();
  
  useEffect(() => {
    startTracking({
      tripId,
      interval: 30000, // 30 seconds
      enableBackground: true
    });
    
    return () => stopTracking();
  }, [tripId]);
  
  return (
    <View>
      {currentLocation && (
        <Text>
          Current: {currentLocation.latitude}, {currentLocation.longitude}
        </Text>
      )}
    </View>
  );
};

Web Dashboard

// Real-time location display
const LocationMap = ({ tripId }) => {
  const [locations, setLocations] = useState([]);
  
  useEffect(() => {
    const ws = new WebSocket('wss://api.bookovia.com/v1/streaming/locations');
    
    ws.onmessage = (event) => {
      const location = JSON.parse(event.data);
      if (location.trip_id === tripId) {
        setLocations(prev => [...prev, location]);
      }
    };
    
    return () => ws.close();
  }, [tripId]);
  
  return <MapComponent locations={locations} />;
};

Next Steps

Safety Analytics

Learn how location data powers safety scoring and driver behavior analysis

Real-time Streaming

Understand WebSocket connections for live location updates

Location API Reference

Explore detailed API documentation for location endpoints

Trip Management

See how locations integrate with trip lifecycle management

Ready to implement location tracking? Check out our quickstart guide for step-by-step integration examples.

Get Started

Core Concepts

Integration Guides

Documentation Index

​Locations

​What is Location Data?

​Location Point Structure

​Core Properties

​Data Validation

​Location Upload Methods

​Single Location Upload

​Batch Location Upload

​Route Generation

​Automatic Route Creation

​Route Data Structure

​Geofencing

​Creating Geofences

​Geofence Types

​Geofence Events

​Location Analytics

​Speed Analysis

​Stop Detection

​Idle Time Calculation

​Address Resolution

​Forward Geocoding

​Reverse Geocoding

​Nearby Services

​Points of Interest

​Data Quality Management

​Quality Metrics

​Data Filtering

​Quality Indicators

​Privacy and Security

​Data Privacy

​Security Measures

​Best Practices

​Upload Optimization

​Performance Tips

​Troubleshooting

​Common Issues

​Use Cases

​Fleet Tracking

​Delivery Optimization

​Safety Monitoring

​Integration Examples

​Mobile App Integration

​Web Dashboard

​Next Steps