Skip to main content

Location History Mutations

Mutations for managing location history data.

createLocationHistory​

Creates a new location history record.

Arguments​

"""
Input for creating location history.
"""
input CreateLocationHistoryInput {
  """
  ID of the tracker this location belongs to.
  """
  trackerId: ID!

  """
  Latitude coordinate.
  """
  latitude: Float!

  """
  Longitude coordinate.
  """
  longitude: Float!

  """
  Timestamp when this location was recorded.
  """
  timestamp: DateTime!
}

Example Mutation​

mutation CreateLocationHistory {
  createLocationHistory(
    input: {
      trackerId: "123"
      latitude: 37.7749
      longitude: -122.4194
      timestamp: "2023-01-01T12:00:00Z"
    }
  ) {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
    tracker {
      id
      name
    }
  }
}

deleteLocationHistory​

Deletes a location history record.

Arguments​

"""
ID of the location history record to delete.
"""
id: ID!

Example Mutation​

mutation DeleteLocationHistory {
  deleteLocationHistory(id: "123")
}

processLocationHistoryGeocoding​

Processes geocoding for a list of location history records.

Arguments​

"""
List of location history IDs to process geocoding for.
"""
locationIds: [ID!]!

Example Mutation​

mutation ProcessGeocoding {
  processLocationHistoryGeocoding(locationIds: ["123", "124"]) {
    id
    nearestCity
    location {
      latitude
      longitude
    }
  }
}

Error Handling​

Common Errors​

Error CodeDescription
INVALID_COORDINATESInvalid latitude/longitude values
INVALID_TIMESTAMPInvalid timestamp format
TRACKER_NOT_FOUNDTracker ID not found
LOCATION_NOT_FOUNDLocation history ID not found

Example Error Response​

{
  "errors": [
    {
      "message": "Invalid coordinates",
      "extensions": {
        "code": "INVALID_COORDINATES",
        "latitude": 91,
        "longitude": -122.4194
      }
    }
  ]
}

LocationHistoryOrderField​

Enum for specifying location history ordering fields.

enum LocationHistoryOrderField {
  """
  Order by timestamp of the location record.
  """
  TIMESTAMP
}

Ordering Example​

query GetOrderedLocationHistory {
  locationHistoryByTracker(
    trackerId: "123"
    orderBy: { field: TIMESTAMP, direction: DESC }
  ) {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
  }
}

Best Practices​

  1. Ordering and Filtering

    • Use appropriate ordering for time-series analysis
    • Consider performance implications of ordering large datasets
    • Combine ordering with filtering for efficient queries

  2. Coordinate Validation

    • Latitude must be between -90 and 90
    • Longitude must be between -180 and 180

  3. Timestamps

    • Use ISO 8601 format
    • Ensure timestamps are not in the future
    • Consider timezone handling

  4. Geocoding

    • Process geocoding asynchronously
    • Handle rate limits
    • Cache results when possible

  5. Performance

    • Use batch operations when possible
    • Consider data retention policies
    • Handle large datasets appropriately
    • Implement appropriate indexes for ordering fields
    • Cache frequently accessed ordered results