Что такое GeoJSON? Формат, типы геометрий и подводные камни

GeoJSON, это JSON-формат, который читает каждая современная веб-карта. Если вы когда-либо рисовали полигон на карте Leaflet, стилизовали векторный слой в MapLibre или хранили зону обслуживания в PostGIS, вы работали с GeoJSON, даже если расширение файла говорило о чём-то другом.

В этом руководстве разбираем, что такое GeoJSON на самом деле, что значат его типы геометрий, где он применяется в реальных системах и какие подводные камни кусают команды, когда GeoJSON-файлы покидают ноутбук разработчика и попадают в продакшен.

Что такое GeoJSON на самом деле

GeoJSON, это открытый формат кодирования географических структур данных, стандартизированный IETF как RFC 7946 в 2016 году. Это строгое подмножество JSON: каждый GeoJSON-документ, это валидный JSON, но спецификация добавляет правила о том, какие ключи разрешены, как структурируется геометрия и как упорядочиваются координаты.

Формат намеренно небольшой. В спецификации всего девять типов объектов верхнего уровня, и компетентный разработчик может удержать их все в голове. Именно эта компактность сделала GeoJSON lingua franca веб-картографии: его легко читать, легко писать и легко валидировать.

Координаты всегда записываются как [longitude, latitude] (с опциональной высотой третьим значением), а система координат зафиксирована на WGS84, том же датуме, который использует GPS вашего телефона. Никаких переговоров, никаких метаданных проекции, никаких споров о порядке осей. Один датум, один порядок, повсюду.

Типы геометрий

GeoJSON определяет семь типов геометрий. Первые три, это примитивы:

• Point: одна координата, используется для булавок, адресов и отдельных датчиков
• LineString: упорядоченный список из двух или более координат, используется для маршрутов, дорог и рек
• Polygon: замкнутое кольцо координат (первая и последняя точка идентичны), используется для зданий, участков и административных границ

Следующие три, это просто коллекции этих примитивов:

• MultiPoint: много точек в одной геометрии, полезно для представления сети магазинов как одного объекта
• MultiLineString: много линий, используется для фрагментированных маршрутов или речных систем
• MultiPolygon: много полигонов, правильный выбор для любой страны с островами (то есть почти для всех)

Седьмой, GeometryCollection, может содержать смесь любых из вышеперечисленных. Спецификация не рекомендует его использовать, потому что большинство потребителей плохо его обрабатывают, и он почти никогда не нужен. Если вы тянетесь к GeometryCollection, это обычно знак, что модели стоит быть FeatureCollection.

Feature и FeatureCollection

Сама по себе геометрия редко полезна. Нужно знать, что она представляет. Для этого и нужен Feature: Feature оборачивает геометрию объектом properties, содержащим произвольные метаданные.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.8952, 52.3702]
  },
  "properties": {
    "name": "Amsterdam Centraal",
    "type": "station",
    "platforms": 15
  }
}

FeatureCollection, это список Feature'ов. Почти каждый реальный GeoJSON-файл, который вы встретите в дикой природе, это FeatureCollection, потому что в реальных датасетах много объектов.

Ключевое дизайн-решение в том, что properties открыты. Спецификация ничего не говорит о том, какие ключи там могут быть и какие типы должны быть у значений. Это не баг, а фича: это значит, что GeoJSON работает для уличной мебели, избирательных границ, зон доставки и AIS-треков судов без необходимости расширять формат. Это также значит, что потребители должны быть осторожны: если вы зависите от существования properties.population, валидируйте это сами, потому что RFC 7946 этого не сделает.

Где применяется GeoJSON

Стоит начать смотреть, и GeoJSON оказывается повсюду в геопространственном стеке:

• Картографические библиотеки: MapLibre GL, Mapbox GL, Leaflet и OpenLayers нативно потребляют GeoJSON как источник данных для слоёв
• Пайплайны векторных тайлов: инструменты вроде Tippecanoe принимают GeoJSON и выдают наборы MVT (Mapbox Vector Tile)
• Спецификации стилей карт: Mapbox Style Specification, используемая в MapLibre, ссылается на GeoJSON как на источник первого класса
• Пространственные базы данных: PostGIS, BigQuery GIS и Snowflake импортируют и экспортируют GeoJSON через выделенные функции
• Выходы API: большинство современных API геокодирования, изохрон и маршрутизации возвращают GeoJSON Features в результатах, чтобы ответ можно было сразу нанести на карту
• Полилинии маршрутов: навигационные ответы обычно включают LineString-геометрию для маршрута, готовую к отрисовке
• Обмен данными: порталы открытых данных, экспорты OpenStreetMap и государственные релизы границ по умолчанию используют GeoJSON, когда целятся в веб-пользователей

Если инструмент вообще говорит на каком-либо геопространственном формате, он почти наверняка говорит на GeoJSON.

Подводные камни в продакшене

GeoJSON прощает в первый день и не прощает на девяностый. Ловушки, в которые попадают команды:

Долгота первой. RFC 7946 фиксирует порядок как [lon, lat]. Люди, адреса и большая часть документации пишут lat, lon. Перестановка их местами, это самый частый баг GeoJSON, и ваша точка оказывается не в том океане.

Порядок обхода полигонов. RFC 7946 указывает, что внешние кольца должны идти против часовой стрелки, а внутренние (отверстия), по часовой. Многие старые GeoJSON-файлы это игнорируют. Одним рендерерам всё равно, другие (особенно Mapbox GL с полигонами, пересекающими антимеридиан) рисуют полигон как обратный к задуманному: крошечный остров становится отверстием в океане, покрывающем остальной мир.

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

Отсутствие нативной поддержки CRS за пределами WGS84. RFC 7946 намеренно убрал старый член crs. Если ваши данные в национальной сетке (British National Grid, RD New, EPSG:3857), нужно перепроецировать в WGS84 до сериализации. Инструменты, выдающие GeoJSON не в WGS84, формально неконформны.

Размер файла. FeatureCollection с миллионами детальных полигонов может раздуться до гигабайт. Для доставки в браузер переключайтесь на векторные тайлы, упрощайте геометрию через Douglas-Peucker или стримите newline-delimited GeoJSON (.ndjson).

Валидация. Используйте линтер вроде GeoJSONLint или библиотеку geojson-validation в CI. Поймать неверный порядок обхода или перепутанные координаты на этапе сборки дешевле, чем ловить это по тикету клиента.

GeoJSON в MapAtlas

GeoJSON, это формат обмена данными по умолчанию на платформе MapAtlas. Продукт Dynamic Maps принимает GeoJSON-источники напрямую для кастомных оверлеев, стилизации и интерактивных слоёв, без предварительной обработки.

Geocoding API возвращает сматченные адреса как GeoJSON Features, так что результат прямого геокодирования можно сразу нанести на карту или сохранить в PostGIS без переразметки полей. Isochrone API возвращает зоны времени в пути как GeoJSON-полигоны, что означает: запрос «места, достижимые за 15 минут», это один fetch и один вызов addSource от появления на экране.

GeoJSON не блестящий. Это маленькое, опинионированное подмножество JSON с фиксированным порядком координат и горсткой типов геометрий. Но это формат, позволяющий каждому слою современного location-стека, от пространственной базы данных до картографического канваса, договориться о том, что такое место. Соблюдайте порядок долготы, валидируйте обход колец, и остальной стек обычно сам о себе позаботится.