Location Custom Field

Location custom fields store geographic coordinates (latitude and longitude) for records. They support precise coordinate storage, geospatial queries, and efficient location-based filtering.

Basic Example

Create a simple location field:

mutation CreateLocationField {
  createCustomField(input: {
    name: "Meeting Location"
    type: LOCATION
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a location field with description:

mutation CreateDetailedLocationField {
  createCustomField(input: {
    name: "Office Location"
    type: LOCATION
    projectId: "proj_123"
    description: "Primary office location coordinates"
  }) {
    id
    name
    type
    description
  }
}

Input Parameters

CreateCustomFieldInput

Setting Location Values

Location fields store latitude and longitude coordinates:

mutation SetLocationValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    latitude: 40.7128
    longitude: -74.0060
  })
}

SetTodoCustomFieldInput Parameters

Note: While both parameters are optional in the schema, both coordinates are required for a valid location. If only one is provided, the location will be invalid.

Coordinate Validation

Valid Ranges

Example Coordinates

Creating Records with Location Values

When creating a new record with location data:

mutation CreateRecordWithLocation {
  createTodo(input: {
    title: "Site Visit"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "location_field_id"
      value: "40.7128,-74.0060"  # Format: "latitude,longitude"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      latitude
      longitude
    }
  }
}

Input Format for Creation

When creating records, location values use comma-separated format:

Response Fields

TodoCustomField Response

Important Limitations

No Built-in Geocoding

Location fields store only coordinates - they do not include:

• Address-to-coordinates conversion
• Reverse geocoding (coordinates-to-address)
• Address validation or search
• Integration with mapping services
• Place name lookup

External Services Required

For address functionality, you’ll need to integrate external services:

• Google Maps API for geocoding
• OpenStreetMap Nominatim for free geocoding
• MapBox for mapping and geocoding
• Here API for location services

Example Integration

// Client-side geocoding example (not part of Blue API)
async function geocodeAddress(address) {
  const response = await fetch(
    `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(address)}&key=${API_KEY}`
  );
  const data = await response.json();
  
  if (data.results.length > 0) {
    const { lat, lng } = data.results[0].geometry.location;
    
    // Now set the location field in Blue
    await setTodoCustomField({
      todoId: "todo_123",
      customFieldId: "location_field_456",
      latitude: lat,
      longitude: lng
    });
  }
}

Required Permissions

Error Responses

Invalid Coordinates

{
  "errors": [{
    "message": "Invalid coordinates: latitude must be between -90 and 90",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Invalid Longitude

{
  "errors": [{
    "message": "Invalid coordinates: longitude must be between -180 and 180",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Best Practices

Data Collection

• Use GPS coordinates for precise locations
• Validate coordinates before storing
• Consider coordinate precision needs (6 decimal places ≈ 10cm accuracy)
• Store coordinates in decimal degrees (not degrees/minutes/seconds)

User Experience

• Provide map interfaces for coordinate selection
• Show location previews when displaying coordinates
• Validate coordinates client-side before API calls
• Consider timezone implications for location data

Performance

• Use spatial indexes for efficient queries
• Limit coordinate precision to needed accuracy
• Consider caching for frequently accessed locations
• Batch location updates when possible

Common Use Cases

1. Field Operations

   • Equipment locations
   • Service call addresses
   • Inspection sites
   • Delivery locations

2. Event Management

   • Event venues
   • Meeting locations
   • Conference sites
   • Workshop locations

3. Asset Tracking

   • Equipment positions
   • Facility locations
   • Vehicle tracking
   • Inventory locations

4. Geographic Analysis

   • Service coverage areas
   • Customer distribution
   • Market analysis
   • Territory management

Integration Features

With Lookups

• Reference location data from other records
• Find records by geographic proximity
• Aggregate location-based data
• Cross-reference coordinates

With Automations

• Trigger actions based on location changes
• Create geofenced notifications
• Update related records when locations change
• Generate location-based reports

With Formulas

• Calculate distances between locations
• Determine geographic centers
• Analyze location patterns
• Create location-based metrics

Limitations

• No built-in geocoding or address conversion
• No mapping interface provided
• Requires external services for address functionality
• Limited to coordinate storage only
• No automatic location validation beyond range checking

Related Resources

• Custom Fields Overview - General concepts
• Google Maps API - Geocoding services
• OpenStreetMap Nominatim - Free geocoding
• MapBox API - Mapping and geocoding services