---

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

Parameter	Type	Required	Description
name	String!	✅ Yes	Display name of the location field
type	CustomFieldType!	✅ Yes	Must be LOCATION
description	String	No	Help text shown to users

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

Parameter	Type	Required	Description
todoId	String!	✅ Yes	ID of the record to update
customFieldId	String!	✅ Yes	ID of the location custom field
latitude	Float	No	Latitude coordinate (-90 to 90)
longitude	Float	No	Longitude coordinate (-180 to 180)

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

Coordinate	Range	Description
Latitude	-90 to 90	North/South position
Longitude	-180 to 180	East/West position

Example Coordinates

Location	Latitude	Longitude
New York City	40.7128	-74.0060
London	51.5074	-0.1278
Sydney	-33.8688	151.2093
Tokyo	35.6762	139.6503
São Paulo	-23.5505	-46.6333

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:

Format	Example	Description
"latitude,longitude"	"40.7128,-74.0060"	Standard coordinate format
"51.5074,-0.1278"	London coordinates	No spaces around comma
"-33.8688,151.2093"	Sydney coordinates	Negative values allowed

Response Fields

TodoCustomField Response

Field	Type	Description
id	String!	Unique identifier for the field value
customField	CustomField!	The custom field definition
latitude	Float	Latitude coordinate
longitude	Float	Longitude coordinate
todo	Todo!	The record this value belongs to
createdAt	DateTime!	When the value was created
updatedAt	DateTime!	When the value was last modified

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

Action	Required Role
Create location field	OWNER, ADMIN, or MEMBER in the project
Update location field	OWNER, ADMIN, or MEMBER in the project
Set location value	OWNER, ADMIN, MEMBER, or CLIENT with edit permissions on the record
View location value	Any project member with read access to the record

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