Пользовательское поле местоположения

Создайте поля местоположения для хранения географических координат записей

Пользовательские поля местоположения хранят географические координаты (широту и долготу) для записей. Они поддерживают точное хранение координат, геопространственные запросы и эффективную фильтрацию на основе местоположения.

Простой пример

Создайте простое поле местоположения:

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

Расширенный пример

Создайте поле местоположения с описанием:

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

Входные параметры

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя поля местоположения
`type`	CustomFieldType!	✅ Да	Должно быть `LOCATION`
`description`	String	Нет	Текст помощи, отображаемый пользователям

Установка значений местоположения

Поля местоположения хранят координаты широты и долготы:

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

Параметры SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	ID записи для обновления
`customFieldId`	String!	✅ Да	ID пользовательского поля местоположения
`latitude`	Float	Нет	Координата широты (-90 до 90)
`longitude`	Float	Нет	Координата долготы (-180 до 180)

Примечание: Хотя оба параметра являются необязательными в схеме, обе координаты необходимы для действительного местоположения. Если предоставлена только одна, местоположение будет недействительным.

Проверка координат

Допустимые диапазоны

Координата	Диапазон	Описание
Latitude	-90 to 90	Северная/Южная позиция
Longitude	-180 to 180	Восточная/Западная позиция

Пример координат

Местоположение	Широта	Долгота
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

Создание записей с значениями местоположения

При создании новой записи с данными о местоположении:

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
    }
  }
}

Формат ввода для создания

При создании записей значения местоположения используют формат с разделением запятой:

Формат	Пример	Описание
`"latitude,longitude"`	`"40.7128,-74.0060"`	Стандартный формат координат
`"51.5074,-0.1278"`	London coordinates	Без пробелов вокруг запятой
`"-33.8688,151.2093"`	Sydney coordinates	Допустимы отрицательные значения

Поля ответа

TodoCustomField Response

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для значения поля
`customField`	CustomField!	Определение пользовательского поля
`latitude`	Float	Координата широты
`longitude`	Float	Координата долготы
`todo`	Todo!	Запись, к которой принадлежит это значение
`createdAt`	DateTime!	Когда значение было создано
`updatedAt`	DateTime!	Когда значение было в последний раз изменено

Важные ограничения

Нет встроенной геокодировки

Поля местоположения хранят только координаты - они не включают:

Преобразование адреса в координаты
Обратная геокодировка (координаты в адрес)
Проверка или поиск адресов
Интеграция с картографическими сервисами
Поиск названий мест

Требуются внешние сервисы

Для функциональности адреса вам нужно будет интегрировать внешние сервисы:

Google Maps API для геокодировки
OpenStreetMap Nominatim для бесплатной геокодировки
MapBox для картографирования и геокодировки
Here API для сервисов местоположения

Пример интеграции

// 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
    });
  }
}

Необходимые разрешения

Действие	Необходимая роль
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

Ответы на ошибки

Неверные координаты

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

Неверная долгота

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

Общие случаи использования

Полевые операции
- Местоположения оборудования
- Адреса вызовов на обслуживание
- Места инспекции
- Местоположения доставки
Управление событиями
- Места проведения мероприятий
- Места встреч
- Места конференций
- Места проведения семинаров
Отслеживание активов
- Позиции оборудования
- Местоположения объектов
- Отслеживание транспортных средств
- Местоположения инвентаря
Географический анализ
- Области охвата услуг
- Распределение клиентов
- Рыночный анализ
- Управление территориями

Функции интеграции

С поиском

Ссылки на данные местоположения из других записей
Поиск записей по географической близости
Агрегация данных на основе местоположения
Перекрестная ссылка координат

С автоматизацией

Запуск действий на основе изменений местоположения
Создание уведомлений с геозаборами
Обновление связанных записей при изменении местоположений
Генерация отчетов на основе местоположения

С формулами

Расчет расстояний между местоположениями
Определение географических центров
Анализ паттернов местоположения
Создание метрик на основе местоположения

Ограничения

Нет встроенной геокодировки или преобразования адресов
Не предоставляется интерфейс карт
Требуются внешние сервисы для функциональности адресов
Ограничено только хранением координат
Нет автоматической проверки местоположения, кроме проверки диапазона

Связанные ресурсы

Обзор пользовательских полей - Общие концепции
Google Maps API - Услуги геокодировки
OpenStreetMap Nominatim - Бесплатная геокодировка
MapBox API - Услуги картографирования и геокодировки