Location Type
The Location type represents a geographic location with additional metadata such as timestamp, accuracy, and address information.
Type Definition
"""
Represents a geographic location with metadata and address information.
"""
type Location {
"""
Unique identifier for the location.
"""
id: ID!
"""
The geographic coordinates of the location.
"""
coordinates: Coordinates!
"""
Timestamp when this location was recorded.
Unix timestamp in seconds.
"""
timestamp: Int!
"""
The nearest city to this location.
Populated through geocoding.
"""
nearestCity: String
"""
The country where this location is situated.
ISO 3166-1 alpha-2 country code.
"""
country: String
"""
The source of this location data.
"""
source: LocationSource!
"""
Additional metadata about this location.
"""
metadata: LocationMetadata
}
"""
Source of the location data.
"""
enum LocationSource {
"""
GPS data from the tracker device.
"""
GPS
"""
Cellular network triangulation.
"""
CELLULAR
"""
WiFi access point positioning.
"""
WIFI
"""
Manually entered location.
"""
MANUAL
}
"""
Additional metadata about a location.
"""
type LocationMetadata {
"""
Battery level of the device when location was recorded.
Percentage between 0-100.
"""
batteryLevel: Int
"""
Signal strength when location was recorded.
"""
signalStrength: Int
"""
Name of the cellular network if location source is CELLULAR.
"""
networkName: String
"""
Additional custom key-value pairs.
"""
custom: JSONObject
}
Fields
Location Type
| Field | Type | Description |
|---|---|---|
id | ID! | Required. Unique identifier |
coordinates | Coordinates! | Required. Geographic coordinates |
timestamp | Int! | Required. Unix timestamp in seconds |
nearestCity | String | Optional. Nearest city name |
country | String | Optional. ISO country code |
source | LocationSource! | Required. Data source |
metadata | LocationMetadata | Optional. Additional metadata |
LocationMetadata Type
| Field | Type | Description |
|---|---|---|
batteryLevel | Int | Optional. Device battery level (0-100) |
signalStrength | Int | Optional. Signal strength indicator |
networkName | String | Optional. Cellular network name |
custom | JSONObject | Optional. Custom metadata |
Usage
Basic Query
query GetLocation {
location(id: "loc_123") {
id
coordinates {
latitude
longitude
}
timestamp
source
}
}
Detailed Query
query GetDetailedLocation {
location(id: "loc_123") {
id
coordinates {
latitude
longitude
accuracy
altitude
heading
speed
}
timestamp
nearestCity
country
source
metadata {
batteryLevel
signalStrength
networkName
custom
}
}
}
Input Types
Creating Locations
"""
Input type for creating a new location.
"""
input CreateLocationInput {
"""
The tracker ID this location belongs to.
"""
trackerId: ID!
"""
The coordinates of the location.
"""
coordinates: CoordinatesInput!
"""
Unix timestamp in seconds.
Defaults to current time if not provided.
"""
timestamp: Int
"""
Source of the location data.
"""
source: LocationSource!
"""
Optional metadata about the location.
"""
metadata: LocationMetadataInput
}
"""
Input type for location metadata.
"""
input LocationMetadataInput {
batteryLevel: Int
signalStrength: Int
networkName: String
custom: JSONObject
}
Mutations
Creating a Location
mutation CreateLocation {
createLocation(
input: {
trackerId: "tracker_123"
coordinates: { latitude: 37.7749, longitude: -122.4194, accuracy: 10 }
source: GPS
metadata: { batteryLevel: 85, signalStrength: 4 }
}
) {
location {
id
coordinates {
latitude
longitude
}
timestamp
source
}
}
}
Validation
The API enforces these validation rules:
- Timestamp Validation
if timestamp > current_time:
raise ValueError("Timestamp cannot be in the future")
- Metadata Validation
if metadata.batteryLevel is not None:
if not 0 <= metadata.batteryLevel <= 100:
raise ValueError("Battery level must be between 0 and 100")
- Custom Metadata Size
if len(str(metadata.custom)) > MAX_CUSTOM_METADATA_SIZE:
raise ValueError("Custom metadata exceeds size limit")
Best Practices
-
Timestamps
- Always use UTC timestamps
- Store with second precision
- Validate against future dates
-
Metadata
- Keep custom metadata minimal
- Document custom field meanings
- Consider size limits
-
Geocoding
- Cache geocoding results
- Update periodically
- Handle missing data gracefully
-
Performance
- Request only needed fields
- Use pagination for history
- Consider data retention policies