API v0.6 является текущей версией API для редактирования OSM, опубликованной 17-21 апреля 2009.

Перевод на русский язык - 09.01.2026

С апреля 2009 года API неоднократно расширялись и обновлялись:

• In March 2012 to reflect small changes
• In April 2013 after the addition of the Map Notes API
• In January 2016 after the addition of changeset discussions
• In January 2018, compression for diff uploads was added in Supporting Input decompression ^GitHub
• In July 2018 after numerous other smaller backwards compatible changes.
• In December 2019, the expand_bbox endpoint was removed.
• In March 2020, JSON support for OSM element endpoints was added.
• In September 2020, JSON support for user details was added.
• In February 2021, the undocumented, unused and obsolete /changes endpoint was removed.
• In February 2022, limiting the maximum number of relation members in Limits on number of tags and relation members ^GitHub and Introduce relation member limit ^GitHub
• In March 2022, the permissions endpoint was added.
• In April 2022, JSON support for some changeset endpoints ^GitHub was added
• In July 2023, the limit parameter for changeset queries ^GitHub was added
• In September 2023, the bbox parameter for note searches ^GitHub was added
• In September 2023, the comment id for changeset discussion comments ^GitHub was included in API responses
• In September 2023, the ability to read user blocks ^GitHub was added
• In November 2023, Added the ability to rate limit edits ^GitHub
• In June 2024, OAuth 1.0a and HTTP Basic Auth were shut down.
• In June 2024, Add the ability to limit changeset size ^GitHub
• In July 2024, the Messaging API was added.
• On August 25, 2024, with the release of openstreetmap-cgimap 2.0.0, the changeset GET endpoint GET /api/0.6/changeset/#id?include_discussion=true JSON response was changed, to align it with the existing Rails implementation. See the GitHub discussion ^GitHub for more details.
• In November 2024, the ability to subscribe to note discussions ^GitHub was added
• In December 2024 - March 2025, various changes were made to align with Rails default REST routes and for consistency between different endpoints:
  • GET /api/0.6/gpx/#id/details was deprecated in favor of GET /api/0.6/gpx/#id. ^GitHub
  • POST /api/0.6/gpx was added to upload gpx files and POST /api/0.6/gpx/create was deprecated. ^GitHub
  • PUT /api/0.6/user/messages/#id was added to update read status of a message and its POST equivalent was deprecated. ^GitHub
  • Wrapper <messages> element was removed from GET /api/0.6/user/messages/inbox XML Response. ^GitHub
  • POST /api/0.6/[nodes|ways|relations] was added to create elements and PUT /api/0.6/[node|way|relation]/create was deprecated. ^GitHub
  • POST /api/0.6/changeset/comment/#comment_id/hide and POST /api/0.6/changeset/comment/#comment_id/unhide were deprecated in favor of new DELETE /api/0.6/changeset_comments/#id/visibility and POST /api/0.6/changeset_comments/#id/visibility. ^GitHub
  • POST /api/0.6/changeset/#id/subscribe and POST /api/0.6/changeset/#id/unsubscribe were deprecated in favor of new POST /api/0.6/changeset/#id/subscription and DELETE /api/0.6/changeset/#id/subscription. ^GitHub
• In February 2025, the abilities to block users ^GitHub and to read active blocks of a current user ^GitHub were added
• In February 2025, the ability to search changeset comment by author or time ^GitHub was added
• In April 2025, GET /api/0.6/gpx_files.json was added to support JSON response for this API ^GitHub
• In November 2025, the company and social_links properties from the website were added to the GET /api/0.6/user/#id endpoint in the API

Предстоящие / планируемые изменения: (отсутствуют)

Основная информация

Пожалуйста, обратите внимание, что это не официальная документация^[1]. Описанное здесь поведение может измениться в будущем^[2].

Код, обеспечивающий работу API, можно найти на GitHub по адресу openstreetmap/openstreetmap-website/tree/master/app/controllers/api ^GitHub.

Некоторые вызовы API на osm.org обрабатываются CGImap, а его исходный код также доступен на GitHub по адресу zerebubuth/openstreetmap-cgimap ^GitHub

Этот API редактирования основан на идеях RESTful API. Для получения дополнительной информации о RESTful API смотрите wikipedia's Representational State Transfer page.

REST API - это серверный компонент, к которому обращаются клиентские запросы. Запросы RESTful API используют HTTP GET, PUT, POST и DELETE типы запросов для выполнения определенных действий. Полезная нагрузка запроса, если она присутствует, возвращается в формате XML (MIME-тип "application/xml") в кодировке UTF-8. Заголовок HTTP Accept-Encoding может использоваться для запроса сжатых данных. Заголовки Content-Type и Content-Encoding не являются строго необходимыми, поскольку OSM API по умолчанию использует вышеупомянутый формат XML/UTF-8. Смотрите #JSON Format для получения информации об ответах в формате JSON.

Запросы на изменение базы данных авторизуются с помощью OAuth. Запросы на чтение не требуют авторизации (за исключением сведений о пользователе).

Изменения между API v0.5 и API v0.6

Для загрузки данных в целях, отличных от редактирования, см. Загрузка данных - скорее всего, вы будете использовать Overpass API (возможно, с помощью Overpass turbo), Planet.osm или extracts.

URL + аутентификация

Для получения дополнительной информации об использовании OAuth смотрите также основную статью о OAuth

В настоящее время API доступен по следующему URL-адресу: https://api.openstreetmap.org/

При тестировании вашего программного обеспечения с использованием API вам следует рассмотреть возможность использования https://master.apis.dev.openstreetmap.org/ вместо live-api. Ваша учетная запись для реального сервиса находится в другой базе данных, поэтому вам, вероятно, потребуется новое имя пользователя и пароль для тестового сервиса; пожалуйста, посетите эту страницу в браузере, чтобы зарегистрироваться.

Все вызовы API, которые обновляют, создают или удаляют данные, должны выполняться аутентифицированным и авторизованным пользователем. Аутентификация выполняется с использованием OAuth 2.0.

Требуемые области для OAuth 2.0

Для использования полного API v0.6 требуются следующие области OAuth:

• read_prefs
• write_prefs
• write_api
  • write_changeset_comments (в настоящее время включен в write_api)
• read_gpx
• write_gpx
• write_notes
• write_diary (область действия поддерживается OAuth2, но не требуется API v0.6)
• write_redactions
• write_blocks
• consume_messages
• send_messages

Коды ошибок

HTTP status code 400 (Bad request)

Если вы получаете доступ к версии API cgimap, этот код ошибки будет возвращен при сбое OAuth с "Bad OAuth request.".

HTTP status code 401 (Unauthorized)

Вход в систему не удался.

HTTP status code 403 (Forbidden)

Вход в систему был успешным, но пользователю не разрешено выполнять операцию.

Возможно, пользователь был заблокирован, или приложению OAuth не были предоставлены требуемые разрешения. Приложение должно отображать сообщение об ошибке (которое при необходимости будет переведено) и, если оно имеет пользовательский интерфейс конечного пользователя, предоставлять простой способ доступа openstreetmap.org, чтобы узнать причины.

Элементы

Существуют вызовы API для создания, чтения, обновления и удаления трех основных элементов, которые составляют картографические данные для OpenStreetMap. Каждый из них возвращает или ожидает данные для элементов в формате XML.

Пакеты правок

Каждая модификация одного или нескольких элементов должна ссылаться на открытый пакет правок.

Теги

Каждый элемент и пакет правок могут содержать любое количество тегов. Тег - это пара строк Ключ-Значение в Юникоде, каждая из которых содержит до 255 полных символов юникода (именно Юникод-символов, не байт).

Максимальная длина строк

Текущая реализация API в rails и CGImap ограничивает длину строк ключей и значений для объектов, пакетов правки и тегов пользовательских предпочтений, а также ролей участников отношений максимум 255 кодовыми точками UTF-8 в юникоде.

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

Надежная идентификация пользователей

Предыдущий API v0.5 возвращал только отображаемое имя пользователя. Пользователь может обновить его в любое время, и история изменений отображаемого имени не сохраняется. Это означает, что не было способа надежно определить, какой пользователь внес конкретное изменение. API v0.6 включает в себя числовой идентификатор пользователя (user ID) учетной записи в дополнение к отображаемому имени. Например,

<node id="68" ... user="fred" uid="123" />

Для этого по-прежнему требуется, чтобы пользователь обнародовал свои правки. User ID для пользователей, которые ранее вносили анонимные изменения, не будет отображаться. В соответствии с рекомендацией правления OpenStreetMap Foundation, анонимные правки больше не разрешены.

Номера версий/оптимистическая блокировка

Дамп планеты, различия и вызовы API для элементов будут возвращать атрибут version для каждого Node, Way и Relation.

<node id="68" ... version="12" />

Эти номера версий используются для оптимистической блокировки. Чтобы загрузить новую версию объекта, клиенту необходимо предоставить версию объекта, которую он изменяет. Если указанная версия не совпадает с текущей версией сервера, будет возвращена ошибка (HTTP status code 409: Conflict). Это означает, что любой клиент, обновляющий данные, должен будет сохранить номера версий исходных данных. Один элемент может обновляться несколько раз в течение одного пакета правок, и его номер версии каждый раз увеличивается, поэтому для одного пакета правок может быть несколько исторических версий одного элемента.

Кроме того, клиенты теперь могут запрашивать конкретные версии элемента.

Номера версий всегда будут начинаться с 1 и увеличиваться на 1 при каждом изменении элемента. Однако клиентам не следует полагаться на увеличение на 1 при обновлении элемента, а вместо этого извлекать новый номер версии из ответа сервера.

Формат XML

Основная статья: OSM XML

Каждый XML-ответ от сервера преобразуется в элемент <osm>, если не указано иное (например, для загрузки различий или пакета правок). В большинстве более поздних примеров эта обёртка отсутствует.

<osm version="0.6" generator="OpenStreetMap server">
	...
	...
</osm>

Каждый вызов API также должен быть заключен в элемент <osm>, но атрибуты version и generator могут быть опущены.

Формат JSON

Основная статья: OSM JSON

Формат OSM API JSON format основан на Overpass API JSON format description (но не полностью совместим с ним) и поддерживается для следующих конечных точек:

• получение картографических данных с помощью границ: GET /api/0.6/map
• чтение: GET /api/0.6/[node|way|relation]/#id
• история: GET /api/0.6/[node|way|relation]/#id/history
• версия: GET /api/0.6/[node|way|relation]/#id/#version
• множественная выборка: GET /api/0.6/[nodes|ways|relations]?#parameters
• отношения для элемента: GET /api/0.6/[node|way|relation]/#id/relations
• линии для точки: GET /api/0.6/node/#id/ways
• полный: GET /api/0.6/[way|relation]/#id/full

Кроме того, следующие конечные точки поддерживают формат JSON:

• получение версий API: GET /api/versions
• получение возможностей API: GET /api/capabilities и GET /api/0.6/capabilities
• получение разрешений: GET /api/0.6/permissions
• методы обработки пользовательских данных:
  • сведения о пользователе: GET /api/0.6/user/#id
  • сведения о нескольких пользователях: GET /api/0.6/users?users=#id1,#id2,...,#idn
  • сведения о вошедшем в систему пользователе: GET /api/0.6/user/details
  • настройки вошедшего в систему пользователя: GET /api/0.6/preferences
• заметки:
  • извлечение данных notes с помощью ограничивающей рамки: GET /api/0.6/notes
  • чтение: GET /api/0.6/notes/#id
  • создать новую заметку: POST /api/0.6/notes
  • выполнить поиск заметок: GET /api/0.6/notes/search
• пакеты правок:
  • запрос: GET /api/0.6/changesets
  • чтение: GET /api/0.6/changeset/#id?include_discussion=true
  • подписаться: POST /api/0.6/changeset/#id/subscribe (ответ в формате JSON)
  • отказаться от подписки: POST /api/0.6/changeset/#id/unsubscribe (ответ в формате JSON)
  • комментарий: POST /api/0.6/changeset/#id/comment (ответ в формате JSON)
  • поиск комментариев к пакету правок: GET /api/0.6/changeset_comments (ответ в формате JSON)
  • скрыть комментарий к пакету правок: POST /api/0.6/changeset/comment/#comment_id/hide (ответ в формате JSON)
  • показать комментарий к пакету правок: POST /api/0.6/changeset/comment/#comment_id/unhide (ответ в формате JSON)

Чтобы запросить формат JSON, либо задайте для заголовка HTTP Accept значение application/json, либо используйте суффикс пути к URL-адресу .json.

(Github issue)

Замена корректных HTTP-методов

Подделка метода HTTP-запроса путем указания заголовка X_HTTP_METHOD_OVERRIDE больше не поддерживается (с февраля 2024 года). Неизвестно, когда эта функция была удалена.

Внутренние ошибки при создании ответа

В маловероятном случае возникновения внутренней ошибки при создании ответа на вызов API будет вставлен элемент error. На этом дальнейшая обработка прекращается.

Даже если код возврата HTTP равен 200, а ответ синтаксически корректен, сообщение будет неполным и должно быть удалено с помощью приложений редактирования. Для дальнейшего анализа приложения редактирования ДОЛЖНЫ сообщать пользователю о внутренней ошибке API вместе с сообщением об ошибке, возвращаемым вызовом API.

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="CGImap 0.8.7 (26234 ubuntu)" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
 <way id="4000392204" visible="true" version="1" changeset="1874689" timestamp="2022-07-26T20:56:27Z" user="mmd2" uid="1">
  <nd ref="5004686582"/>
  <nd ref="5004686236"/>
  <nd ref="5004686540"/>
  <nd ref="5004686705"/>
  <nd ref="5004686546"/>
  <nd ref="5004686468"/>
  <nd ref="5004686472"/>
  <tag k="bicycle" v="use_sidepath"/>
  <tag k="highway" v="secondary"/>
  <tag k="maxspeed" v="50"/>
  <tag k="name" v="Bunderstraat"/>
  <tag k="old_ref" v="N586"/>
  <tag k="surface" v="asphalt"/>
 </way>
 <error>Mismatch in tags key and value size</error>
</osm>

{
  "version": "0.6",
  "generator": "CGImap 0.8.7 (22730 ubuntu)",
  "copyright": "OpenStreetMap and contributors",
  "attribution": "http://www.openstreetmap.org/copyright",
  "license": "http://opendatacommons.org/licenses/odbl/1-0/",
  "elements": [
    {
      "type": "way",
      "id": 4000392204,
      "timestamp": "2022-07-26T20:56:27Z",
      "version": 1,
      "changeset": 1874689,
      "user": "mmd2",
      "uid": 1,
      "nodes": [
        5004686582,
        5004686236,
        5004686540,
        5004686705,
        5004686546,
        5004686468,
        5004686472
      ],
      "tags": {
        "bicycle": "use_sidepath",
        "highway": "secondary",
        "maxspeed": "50",
        "name": "Bunderstraat",
        "old_ref": "N586",
        "surface": "asphalt"
      }
    },
    {
      "error": "Mismatch in tags key and value size"
    }
  ]
}

API вызовы

Разное

Доступные версии API: GET /api/versions

Возвращает список версий API, поддерживаемых данным экземпляром.

Ответ сервера XML

GET /api/versions

<?xml version="1.0" encoding="UTF-8"?>
<osm generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
	<api>
		<version>0.6</version>
	</api>
</osm>

Ответ сервера JSON

GET /api/versions.json

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "api": {
  "versions": ["0.6"]
 }
}

Возможности: GET /api/capabilities

Также доступен: GET /api/0.6/capabilities.

Этот вызов API предназначен для предоставления информации о возможностях и ограничениях текущего API.

Ответ

Возвращает документ XML (тип содержимого application/xml)

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
	<api>
		<version minimum="0.6" maximum="0.6"/>
		<area maximum="0.25"/>
		<note_area maximum="25"/>
		<tracepoints per_page="5000"/>
		<waynodes maximum="2000"/>
		<relationmembers maximum="32000"/>
		<changesets maximum_elements="10000" default_query_limit="100" maximum_query_limit="100"/>
		<notes default_query_limit="100" maximum_query_limit="10000"/>
		<timeout seconds="300"/>
		<status database="online" api="online" gpx="online"/>
	</api>
	<policy>
		<imagery>
			<blacklist regex=".*\.google(apis)?\..*/(vt|kh)[\?/].*([xyz]=.*){3}.*"/>
			<blacklist regex="http://xdworld\.vworld\.kr:8080/.*"/>
			<blacklist regex=".*\.here\.com[/:].*"/>
		</imagery>
	</policy>
</osm>

Обратите внимание, что фактические возвращаемые значения могут измениться в любое время, и этот документ XML служит только примером.

• Авторское право, указание авторства и лицензия: ссылка на юридическую информацию

API:

• version minimum и maximum являются ли версии вызовов API, которые сервер будет принимать.
• area maximum - максимальная площадь в квадратных градусах, которая может быть запрошена вызовами API.
• tracepoints per_page - максимальное количество точек в одной треке GPS. (Возможно, неверно)
• waynodes maximum - максимальное количество точек, которое может содержать линия.
• relationmembers maximum - максимальное количество участников, которое может содержать отношение. (добавлено в феврале 2022)
• changesets maximum_elements - максимальное количество объединенных точек, линий и отношений, которые могут содержаться в пакете правок.
• changesets default_query_limit и maximum_query_limit являются значением по умолчанию и максимальным значением предельного параметра для запросов пакетов правки. (добавлено в августе 2023 ^GitHub)
• notes default_query_limit и maximum_query_limit являются значением по умолчанию и максимальным значением предельного параметра для заметок запросов с границей и поиска. (добавлено в августе 2023 ^GitHub)
• возвращает элемент status, либо online, readonly или offline для каждой из баз данных, API и GPX API. Поле database является информационным, и поля api/gpx указывают, должен ли клиент ожидать, что запросы на чтение и запись будут работать (online), для работы используются только запросы на чтение (readonly) или нет запросов на работу (offline).

Политика:

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

Примечания

• в настоящее время существуют как версионные (/api/0.6/capabilities), так и неверсированные (/api/capabilities) версии этого вызова. Неверсионный вариант устарел ^GitHub из-за того, что сначала рекомендуется проверить доступные версии, а затем получить доступ к возможностям конкретной версии.
• идентификаторы элементов и участников отношений в настоящее время зависят от реализации и ограничены 64-разрядными целыми числами со знаком, это не должно быть проблемой :-).

Получение картографических данных ограниченных прямоугольником: GET /api/0.6/map

Следующая команда возвращает:

• все точки, находящиеся внутри заданного ограничивающего прямоугольника, и любые отношения, которые ссылаются на них.
• все линии, которые ссылаются по крайней мере на одну точку, находящийся внутри данного ограничивающего прямоугольника, любые отношения, которые ссылаются на них [линии], и любые точки за пределами ограничивающего прямоугольника, на которые могут ссылаться линии.
• все отношения, которые ссылаются на одну из точек, линий или отношений, включенных в соответствии с вышеуказанными правилами. (Применяется ли не рекурсивно, смотрите объяснение ниже.)

GET /api/0.6/map?bbox=left,bottom,right,top

где:

• left - долгота левой (самой западной) стороны ограничивающего прямоугольника.
• bottom - широта нижней (самой южной) стороны ограничивающего прямоугольника.
• right - долгота правой (самой восточной) стороны ограничивающего прямоугольника.
• top - широта верхней (самой северной) стороны ограничивающего прямоугольника.

Обратите внимание, что, хотя эта команда возвращает те отношения, которые ссылаются на вышеупомянутые точки и линии, обратное неверно: она не обязательно возвращает все точки и линии, на которые ссылаются эти отношения. Это предотвращает неоправданно большие результирующие пакеты. Например, представьте случай, когда:

• существует отношение с именем "Russia", которое ссылается на каждую точку в России.
• точки, линии и отношения извлекаются для ограничивающего прямоугольника, охватывающего небольшую часть России.

Хотя результат будет включать точки, линии и отношения, указанные в правилах для команды, включая отношение "Russia", он (случайно) не будет включать все точки и линии в России. При желании точки и линии, на которые ссылается отношение "Russia", могут быть получены по их соответствующим идентификаторам. Также обратите внимание, что линии, которые пересекают ограничивающий прямоугольник, но не имеют точек внутри ограничивающего прямоугольника, возвращены не будут.

Коды ошибок

HTTP status code 400 (Bad Request)

при превышении любого из ограничений на количество точек/линий/отношений, в частности, если вызов возвращает более 50 000 точек. Другие варианты использования этого кода приведены выше.

HTTP status code 509 (Bandwidth Limit Exceeded)

"Ошибка: вы загрузили слишком много данных. Пожалуйста, повторите попытку позже." Смотрите Часто задаваемые вопросы для разработчиков.

Пакеты правок

Чтобы упростить идентификацию связанных изменений, введена концепция пакетов правок. Каждая модификация стандартных элементов OSM должна ссылаться на открытый пакет правок. Набор изменений может содержать теги, как и другие элементы. Рекомендуемым тегом для пакетов правок является ключ Template:Ключ с кратким, понятным для человека описанием изменений, вносимых в этот пакет правок, аналогично сообщению о фиксации в системе контроля версий. Новый пакет правок может быть открыт в любое время, и на него можно ссылаться из нескольких вызовов API. Из-за этого он может быть закрыт вручную, поскольку сервер не может знать, когда заканчивается один пакет правок и должен начаться другой. Чтобы избежать устаревания открытых пакетов правок, реализован механизм автоматического закрытия пакетов правок при выполнении одного из следующих трех условий:

• 10 000 правок в одном пакете правок (конкретные ограничения приведены в разделе конечная точка возможностей)
• пакет правок открыт более 24 часов
• за 1 час (т.е. время ожидания) не было произведено никаких изменений/вызовов API, связанных с пакетом правок.

Обратите внимание, что некоторые старые пакеты правок могут содержать чуть более 10 тыс. (или ранее 50 тыс.) изменений из-за некоторых сбоев в API.

Пакеты правок, в частности, "не являются" атомарными - элементы, добавленные в пакет правок, будут видны другим пользователям до того, как пакет правок будет закрыт. Учитывая, сколько изменений может быть загружено за один шаг, это невозможно. Вместо этого используется оптимистическая блокировка, как описано выше. Все, что отправляется на сервер в рамках одного запроса, будет рассматриваться атомарно. Для обеспечения транзакционности при нескольких изменениях существует новый вызов API "diff upload".

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

Для упрощения использования сервер сохраняет ограничивающую рамку для каждого пакета правок и позволяет пользователям запрашивать пакеты правок в определенной области. Это будет вычислено сервером, поскольку ему в любом случае необходимо найти соответствующие узлы. Клиент должен иметь в виду, что если пользователи вносят много небольших изменений в большой области, они будут легко сопоставлены. В этом случае клиенты должны непосредственно изучить пакет правок, чтобы убедиться, что они действительно совпадают.

В данный момент невозможно удалить пакеты правок, даже если они не содержат никаких изменений. Позже сервер может удалить закрытые пакеты правок, которые не содержат никаких изменений. Это еще не реализовано.

Вычисление ограничивающего прямоугольника

Вот как API вычисляет ограничивающий прямоугольник, связанный с пакетом правок:

• точки: любое изменение точки, включая удаление, добавляет старое и новое местоположение точки в ограничивающий прямоугольник.
• линии: любое изменение линии, включая удаление, добавляет все точки линии пути в ограничивающий прямоугольник.
• отношения:
  • добавление или удаление точек или линий из отношения приводит к их добавлению в ограничивающий прямоугольник пакета правок.
  • добавление участников отношения элемента или изменение значений тегов приводит к добавлению всех участников точек и линий в ограничивающий прямоугольник.
  • это похоже на то, как работает вызов map, и разумно при условии, что добавление или удаление участников существенно не изменяет остальную часть отношения.

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

Создать: PUT /api/0.6/changeset/create

Полезной нагрузкой запроса на создание пакета правок являются метаданные этого пакета правок. Тело запроса должно содержать один или несколько элементов changeset, которые необязательно включают произвольное количество тегов (таких как 'comment', 'created_by', ...). Все элементы changeset должны быть заключены в элемент osm.

The payload of a changeset creation request has to be one or more changeset elements optionally including an arbitrary number of tags.

<osm>
	<changeset>
		<tag k="created_by" v="JOSM 1.61"/>
		<tag k="comment" v="Just adding some streetnames"/>
		...
	</changeset>
	...
</osm>

Если в XML имеется несколько элементов changeset, то используются теги из всех них, причем более поздние теги переопределяют более ранние в случае дублирования ключей.

Максимальная длина тегов пакета правок составляет 255 символов, как и у обычных тегов. Это относится отдельно к ключу и значению.

Ответ сервера

Идентификатор вновь созданного ПАКЕТА ПРАВОК с типом содержимого text/plain.

Коды ошибок

HTTP status code 400 (Bad Request)

при возникновении ошибок при разборе файла XML

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP PUT,

Примечания

Допускается любое количество тегов, возможно, зависящих от редактора. Редактор может, например, автоматически включать информацию о том, какое фоновое изображение было использовано, или даже некоторую информацию о внутреннем состоянии, которая облегчит повторный просмотр пакета правок в том же редакторе позже и т.д.

Клиенты должны включать тег created_by=*. Клиентам рекомендуется убедиться, что присутствует тег comment=*, который ввел пользователь. На данный момент это необязательно, но это может измениться в более поздних версиях API. Клиенты не должны автоматически создавать тег комментария, поскольку этот тег предназначен для описания изменений конечным пользователем. Клиенты могут добавлять любые другие теги по своему усмотрению.

Прочитать: GET /api/0.6/changeset/#id?include_discussion=true

Возвращает пакет правок с заданным id в формате OSM-XML.

Параметры

id

идентификатор извлекаемого пакета правок

include_discussion

указывает, должен ли результат содержать обсуждение пакета правок или нет. Если для этого параметра задано какое-либо значение, возвращается обсуждение. Если оно пустое или опущено, обсуждения в результате не будет.

Ответ сервера XML

Возвращает единственный элемент пакета правок, содержащий теги пакета правок с типом содержимого application/xml

GET /api/0.6/changeset/#id?include_discussion=true

<osm version="0.6" generator="CGImap 0.9.3 (987909 spike-08.openstreetmap.org)" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
	<changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
		<tag k="created_by" v="JOSM 1.61"/>
		<tag k="comment" v="Just adding some streetnames"/>
		...
		<discussion>
			<comment id="1234" date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
				<text>Did you verify those street names?</text>
			</comment>
			<comment id="5678" date="2015-01-01T18:58:03Z" uid="123" user="fred">
				<text>sure!</text>
			</comment>
			...
		</discussion>
	</changeset>
</osm>

Ответ сервера JSON

Возвращает единственный элемент пакета правок, содержащий теги пакета правок с типом содержимого application/json

GET /api/0.6/changeset/#id.json?include_discussion=true

Пожалуйста, обратите внимание, что формат JSON был изменен 25 августа 2024 года с выпуском openstreetmap-cgimap 2.0.0, чтобы привести его в соответствие с существующим форматом Rails.

{
  "version": "0.6",
  "generator": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
  "copyright": "OpenStreetMap and contributors",
  "attribution": "http://www.openstreetmap.org/copyright",
  "license": "http://opendatacommons.org/licenses/odbl/1-0/",
  "changeset": {
    "id": 10,
    "created_at": "2005-05-01T16:09:37Z",
    "open": false,
    "comments_count": 1,
    "changes_count": 10,
    "closed_at": "2005-05-01T17:16:44Z",
    "min_lat": 59.9513092,
    "min_lon": 10.7719727,
    "max_lat": 59.9561501,
    "max_lon": 10.7994537,
    "uid": 24,
    "user": "Petter Reinholdtsen",
    "comments": [
      {
        "id": 836447,
        "visible": true,
        "date": "2022-03-22T20:58:30Z",
        "uid": 15079200,
        "user": "Ethan White of Cheriton",
        "text": "wow no one have said anything here 3/22/2022\n"
      }
    ]
  }
}

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти набор изменений с заданным идентификатором

Примечания

• uid может быть недоступен для пакета правок, которые автоматически сгенерированные при переходе с API v0.5 на API v0.6;
• атрибуты ограничивающего прямоугольника будут отсутствовать для пустого пакета правок;
• ограничивающий прямоугольник пакета правок - это прямоугольник, который содержит ограничивающие рамки всех объектов, измененных в этом пакете правок. Необязательно, чтобы это был наименьший из возможных прямоугольников.
• этот вызов API возвращает только информацию о самом пакете правок, но не о фактических изменениях, внесенных в элементы этого пакета правок. Чтобы получить доступ к этой информации, используйте вызов API download.

Обновить: PUT /api/0.6/changeset/#id

Для обновления тегов в пакете правок, например, пакет правок comment=foo.

Полезной нагрузкой должен быть документ OSM, содержащий новую версию одного пакета правок. Ограничивающий прямоугольник, время обновления и другие атрибуты игнорируются и не могут быть обновлены этим методом. Для обновления ограничивающего прямоугольника обратитесь к методу expand_bbox.

<osm>
	<changeset>
		<tag k="comment" v="Just adding some streetnames and a restaurant"/>
	</changeset>
</osm>

Параметры

id

идентификатор обновляемого пакета правок. Пользователь, выполняющий этот вызов API, должен быть тем же, кто создал пакет правок

Ответ сервера

Документ OSM, содержащий новую версию пакета правок с типом содержимого application/xml

Коды ошибок

HTTP status code 400 (Bad Request)

при возникновении ошибок при разборе файла XML

HTTP status code 404 (Not Found)

когда не удалось найти пакет правок с заданным идентификатором

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP PUT,

HTTP status code 409 (Conflict) - text/plain

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at.".

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

Примечания

Неизмененные теги должны быть повторены, чтобы их нельзя было удалить.

Закрыть: PUT /api/0.6/changeset/#id/close

Закрывает пакет правок. Возможно, пакет правок уже был закрыт без выполнения владельцем этого вызова API. В этом случае возвращается код ошибки.

Параметры

id

идентификатор пакета правок, который нужно закрыть. Пользователь, выполняющий этот вызов API, должен быть тем же, кто создал пакет правок.

Ответ сервера

При успешном закрытии пакета правок ничего не возвращается (HTTP status code 200)

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти пакет правок с заданным идентификатором

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP PUT,

HTTP status code 409 (Conflict) - text/plain

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at.".

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

Загрузить: GET /api/0.6/changeset/#id/download

Возвращает документ OsmChange, описывающий все изменения, связанные с пакетом правок.

Параметры

id

идентификатор пакета правок, для которого запрашивается OsmChange.

Ответ сервера

OsmChange XML с типом содержимого application/xml.

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти пакет правок с заданным идентификатором

Примечания

• результат этого вызова может измениться до тех пор, пока открыт пакет правок;
• элементы в OsmChange сортируются по временной метке и номеру версии;
• существует отдельный вызов, позволяющий получить только информацию о самом пакете правок.

Расширить ограничивающую рамку: POST /api/0.6/changeset/#id/expand_bbox (устарел, удалено)

Примечание: эта конечная точка была удалена в декабре 2019 года. Смотрите здесь GitHub issue.

Запрос: GET /api/0.6/changesets

Это метод API для получения списка пакета правок. Он поддерживает фильтрацию по различным критериям.

При выполнении нескольких запросов результатом будут те, которые соответствуют всем требованиям. Содержимое возвращаемого документа - это пакеты правок и их теги. Чтобы получить полный пакет правок, связанных с пакетом правок, используйте метод download для каждого идентификатора пакета правок в отдельности.

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

Этот вызов возвращает пакеты правок, соответствующие критериям, упорядоченные по времени их создания. По умолчанию сначала выбирается самый новый, но вы можете указать order=oldest, чтобы изменить порядок сортировки^[3]. Обратный порядок не может быть объединен с time.

Параметры

bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N)

найти пракеты правок в пределах заданного ограничивающего прямоугольника

user=#uid или display_name=#name

найти изменения, внесенные пользователем с указанным идентификатором пользователя или отображаемым именем. Указание обоих параметров является ошибкой.

time=T1

найти пакеты правок, закрытые после T1. Сравните с from=T1, который вместо этого фильтрует по времени создания.

time=T1,T2

найти пакеты правок, которые были закрытые после T1 и открытые до T2. Другими словами, все пакеты правок, которые были открыты в какой-то момент в течение заданного периода времени с T1 по T2.

from=T1 [& to=T2]

найти пакеты правок, созданные в T1 или после него, и (необязательно) до T2. Для to требуется from, но не наоборот. Если указано только to, это не имеет никакого эффекта.

open=true

найти только те пакеты правок, которые все еще открытые, но исключает те, которые закрыты или достигли предельного количества элементов для пакета правок (на данный момент - 10.000^[4])

closed=true

найти только те пакеты правок, которые закрытые или достигли предельного количества элементов

changesets=#cid{,#cid}

найти пакеты правок с указанными идентификаторами (начиная с 2013-12-05)

order=[newest|oldest]

если newest (по умолчанию), сначала отсортировать самые новые пакеты правок. Если oldest, то в обратном порядке.

limit=N

указывает максимальное количество возвращенных пакетов правок. Число от 1 до максимального предельного значения (в настоящее время 100). Если оно опущено, используется предельное значение по умолчанию (в настоящее время 100). Фактические максимальные значения и предельные значения по умолчанию можно найти с помощью |запроса возможностей.

Формат времени: Все, что будет проанализировано функцией Ruby Time.parse.

Ответ сервера

Возвращает список всех пакетов правок, упорядоченных по дате создания. Элемент <osm> может быть пустым, если запрос не дал результатов. Ответ отправляется с типом содержимого application/xml.

Коды ошибок

HTTP status code 400 (Bad Request) - text/plain

при неправильном формировании параметров. Возвращается текстовое сообщение с объяснением ошибки. В частности, попытка указать UID и отображаемое имя в качестве параметров запроса пользователя приведет к этой ошибке

HTTP status code 404 (Not Found)

когда не удалось найти пользователя с указанным uid или display_name

Примечания

• возвращаются только изменения, внесенные общедоступными пользователями;
• возвращается не более 100 изменений.

Разностная выгрузка: POST /api/0.6/changeset/#id/upload

С помощью этого API файлы вызовов в формате OsmChange могут быть загружены на сервер. Это гарантирует выполнение транзакции. Таким образом, либо будут применены все изменения, либо ничего.

Чтобы загрузить OSC-файл, он должен соответствовать спецификации OsmChange со следующими отличиями:

• каждый элемент должен содержать атрибут changeset и version, за исключением случаев, когда вы создаете элемент, для которого версия не требуется, поскольку сервер устанавливает ее для вас. changeset должен совпадать с идентификатором загружаемого пакета правок.
• блок <delete> в документе OsmChange может содержать атрибут if-unused (значение которого игнорируется). Если этот атрибут присутствует, то операции удаления в этом блоке являются условными и будут выполняться только в том случае, если объект, подлежащий удалению, не используется другим объектом. Без параметра if-unused такая ситуация привела бы к ошибке, и вся разностная выгрузка завершилась бы неудачей. Установка атрибута также приведет к тому, что удаление уже удаленных объектов не приведет к возникновению ошибки.
• документы OsmChange, как правило, имеют атрибуты user и uid для каждого элемента. Они не требуются в документе, загруженном в API.

Параметры

id

идентификатор ПАКЕТА ПРАВОК, к которому относится эта разностная выгрузка.

POST data

данные файла OsmChange

Ответ сервера

Если разность успешно применена, возвращается XML (тип содержимого application/xml) в следующем формате

<diffResult generator="OpenStreetMap Server" version="0.6">
	<node|way|relation old_id="#" new_id="#" new_version="#"/>
	...
</diffResult>

с одним элементом для каждого элемента при выгрузке. Обратите внимание, что это может показаться нелогичным, если один и тот же элемент несколько раз появлялся во входных данных, то он будет появляться несколько раз и в выходных данных.

Коды ошибок

HTTP status code 400 (Bad Request) - text/plain

при возникновении ошибок при синтаксическом анализе XML. Возвращается текстовое сообщение с объяснением ошибки.

когда идентификатор заполнителя отсутствует или не уникален (это будет происходить для ссылок на циклические отношения)

HTTP status code 404 (Not Found)

когда не удалось найти пакет правок с заданным идентификатором

или когда разность содержит элементы, которые не удалось найти для данного идентификатора

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP POST

HTTP status code 409 (Conflict) - text/plain

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at.".

если при выгрузке будет превышен максимальный размер пакета правок. Будет возвращено сообщение в формате "The changeset #id was closed at #closed_at.".

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

или если разность содержит элементы с идентификаторами пакета правок, которые не совпадают с идентификатором пакета правок, в который был загружен в разность

или любые сообщения об ошибках, которые могли возникнуть в результате операции создания, обновления или удаления одного из элементов

HTTP status code 413 (Payload too large/Content too large)

если во время выгрузки будет превышен допустимый размер ограничивающего прямоугольника, будет возвращена ошибка "Changeset bounding box size limit exceeded.".

HTTP status code 429 (Too many requests)

когда запрос был заблокирован из-за ограничения скорости

Другие коды состояния

любые коды ошибок и связанные с ними сообщения, которые могут возникнуть в результате операции создания, обновления или удаления одного из элементов

смотрите соответствующие разделы на этой странице

Примечания

• обработка останавливается при первой ошибке, поэтому, если при одной разностной выгрузке возникает несколько конфликтов, сообщается только о первой проблеме;
• максимальное количество разрешенных изменений в пакете правок приведено в разделе /api/capabilities -> changesets -> maximum_elements;
• в настоящее время размер различий в порту Rails не ограничен. CGImap ограничивает размер diff до 50 МБ (в несжатом виде);
• прямое использование идентификаторов-заполнителей запрещено и будет отклонено API.

Краткое описание пакета правок

Процедура успешного создания пакета правок представлена на следующем рисунке.

Обратите внимание, что на рисунке показаны операции с одним объектом для создания / обновления / удаления элементов в соответствии с API 0.5. По соображениям производительности пользователям API рекомендуется использовать конечную точку разностной загрузки API 0.6.

Обсуждение пакета правок

Обсуждения пакета правок были добавлены в ноябре 2014 года (смотрите блог).

Комментарий: POST /api/0.6/changeset/#id/comment

Добавить комментарий к пакету правок. Пакет правок должен быть закрыт.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/comment (example)
Return type: application/xml

Этот запрос должен быть выполнен от имени авторизованного пользователя.

Параметры

text

текст комментария. Тип содержимого - application/x-www-form-urlencoded.

Коды ошибок

HTTP status code 400 (Bad Request)

если текстовое поле отсутствовало

HTTP status code 409 (Conflict)

пакет правок не закрыт

Примечания

• требуется write_api или write_changeset_comments области действия OAuth

Подписаться: POST /api/0.6/changeset/#id/subscription

Также доступно по запросу POST /api/0.6/changeset/#id/subscribe (устарело)

Подписаться на обсуждение пакета правок, чтобы получать уведомления о новых комментариях.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/subscription (example)
Return type: application/xml

Этот запрос должен быть выполнен от имени авторизованного пользователя.

Коды ошибок

HTTP status code 409 (Conflict)

если пользователь уже подписан на этот пакет правок

Отписаться: DELETE /api/0.6/changeset/#id/subscription

Также доступно по запросу POST /api/0.6/changeset/#id/unsubscribe (устарело)

Отменить подписку на обсуждение пакета правок, чтобы прекратить получать уведомления.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/subscription (example)
Return type: application/xml

Этот запрос должен быть выполнен от имени авторизованного пользователя.

Коды ошибок

HTTP status code 404 (Not Found)

если пользователь не подписан на этот пакет правок

Поиск комментариев к пакету правок: GET /api/0.6/changeset_comments

Возвращает комментарии к наборупакету правок, соответствующие указанному запросу. Если запрос не задан, возвращаются самые последние комментарии к пакету правок.

URL: https://api.openstreetmap.org/api/0.6/changeset_comments

Параметры

Примеры

Смотреть последние комментарии к пакету правок по всему миру:

 https://api.openstreetmap.org/api/0.6/changeset_comments

Поиск комментариев к пакету правок от конкретного пользователя:

 https://api.openstreetmap.org/api/0.6/changeset_comments?display_name=Steve

Поиск комментариев к пакетам правок в период с 1 по 2 января 2015 года:

 https://www.openstreetmap.org/api/0.6/changeset_comments?from=2015-01-01&to=2015-01-02

Коды ошибок

HTTP status code 400 (Bad Request)

когда нарушается какой-либо из этих пределов

Скрыть комментарий к пакету правок: DELETE /api/0.6/changeset_comments/#id/visibility

Также доступно по запросу POST /api/0.6/changeset/comment/#comment_id/hide (устарело)

Устанавливает флажок visible в комментарии к пакету правок в значение false.

URL: https://api.openstreetmap.org/api/0.6/changeset_comments/#id/visibility
Return type: application/xml

Этот запрос должен быть выполнен от имени авторизованного пользователя с ролью модератора.

Обратите внимание, что идентификатор комментария к пакету правок отличается от идентификатора пакета правок.

Коды ошибок

HTTP status code 403 (Forbidden)

если пользователь не является модератором

HTTP status code 404 (Not Found)

если идентификатор комментария к пакету правок неизвестен

Примечания

• требуется write_api или write_changeset_comments области действия OAuth

Отобразить комментарий к пакету правок: POST /api/0.6/changeset_comments/#id/visibility

Также доступно по запросу POST /api/0.6/changeset/comment/#comment_id/unhide (устарело)

Устанавливает флажок visible в комментарии к пакету правок в значение true.

URL: https://api.openstreetmap.org/api/0.6/changeset_comments/#id/visibility
Return type: application/xml

Этот запрос должен быть выполнен от имени авторизованного пользователя с ролью модератора.

Обратите внимание, что идентификатор комментария к пакету правок отличается от идентификатора пакета правок.

Коды ошибок

HTTP status code 403 (Forbidden)

если пользователь не является модератором

HTTP status code 404 (Not Found)

если идентификатор комментария к пакету правок неизвестен

Примечания

• требуется write_api или write_changeset_comments области действия OAuth

Элементы

В OpenStreetMap есть вызовы create, read, update и delete для всех трех основных элементов (Nodes, Ways и Relations). Эти вызовы очень похожи, за исключением полезной нагрузки и нескольких специальных сообщений об ошибках, поэтому они документируются только один раз.

Создать: POST /api/0.6/[nodes|ways|relations]

Также доступно по запросу PUT /api/0.6/[node|way|relation]/create (устарело)

Создает новый элемент указанного типа. Обратите внимание, что весь запрос должен быть заключен в элемент <osm>...</osm>.

Точка:

<osm>
	<node changeset="12" lat="..." lon="...">
		<tag k="note" v="Just a node"/>
		...
	</node>
</osm>

Линия:

<osm>
	<way changeset="12">
		<tag k="note" v="Just a way"/>
		...
		<nd ref="123"/>
		<nd ref="4345"/>
		...
	</way>
</osm>

Отношение:

<osm>
	<relation changeset="12">
		<tag k="note" v="Just a relation"/>
		...
		<member type="node" role="stop" ref="123"/>
		<member type="way" ref="234"/>
	</relation>
</osm>

Если задано несколько элементов, создается только первый. Остальные отбрасываются (это поведение отличается от создания пакета правок).

Ответ сервера

Идентификатор вновь созданного элемента (тип содержимого - text/plain)

Коды ошибок

HTTP status code 400 (Bad Request) - text/plain

при возникновении ошибок при синтаксическом анализе XML. Возвращается текстовое сообщение с объяснением ошибки

когда идентификатор пакета правок отсутствует (к сожалению, сообщения об ошибках не совпадают)

когда точка находится за пределами внешнего мира

когда точек слишком много для определенной линии

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP PUT

HTTP status code 409 (Conflict) - text/plain

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at."

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

HTTP status code 412 (Precondition Failed)

когда на линии есть точки, которые не существуют или не видны (т.е. удалены): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."

когда отношение содержит элементы, которые не существуют или не видны: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

HTTP status code 429 (Too many requests)

когда запрос был заблокирован из-за ограничения скорости

Примечания

• это обновляет ограничивающий прямоугольник пакета правок;
• атрибут role для отношений необязателен. По умолчанию используется пустая строка;
• чтобы избежать проблем с производительностью при загрузке нескольких объектов, настоятельно рекомендуется использовать конечную точку Diff upload.

Прочитать: GET /api/0.6/[node|way|relation]/#id

Возвращает XML-представление элемента.

Ответ сервера XML

GET /api/0.6/[node|way|relation]/#id

XML, представляющий элемент, заключенный в элемент <osm>:

<osm>
	<node id="123" lat="..." lon="..." version="142" changeset="12" user="fred" uid="123" visible="true" timestamp="2005-07-30T14:27:12+01:00">
		<tag k="note" v="Just a node"/>
		...
	</node>
</osm>

Ответ сервера JSON

GET /api/0.6/[node|way|relation]/#id.json

JSON, представляющий элемент, заключенный в элемент <json>:

{
 "version": "0.6",
 "elements": [
  {"type": "node", "id": 4326396331, "lat": 31.9016302, "lon": -81.5990471, "timestamp": "2016-07-31T00:08:11Z", "version": 2, "changeset": 41136027, "user": "maven149", "id": 136601}
 ]
}

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

HTTP status code 410 (Gone)

если элемент был удален

Обновить: PUT /api/0.6/[node|way|relation]/#id

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

Этот пример представляет собой обновление точки 4326396331, обновляющее версию 1 для изменения существующих тегов. Это изменение внесено, пока пакет правок с идентификатором 188021 все еще открыт:

<osm>
	<node changeset="188021" id="4326396331" lat="50.4202102" lon="6.1211032" version="1" visible="true">
		<tag k="foo" v="barzzz" />
	</node>
</osm>

Пример для линии 22935194 с добавлением нового ключа zoning_code со значением B. Помните, что при добавлении PUT к существующему способу вам необходимо добавить все существующие теги (исключив некоторые из них для краткости) и ту же версию, что и версия из OSM

<osm>
     <way id="22935194" changeset="152700179" version="9">
          <tag k="highway" v="residential"/>
          <tag k="zoning_code" v="B"/>
          <tag k="name" v="Strada Desseanu"/>
     </way>
</osm>

Ответ сервера

Возвращает номер новой версии с типом содержимого text/plain.

Коды ошибок

HTTP status code 400 (Bad Request) - text/plain

когда возникают ошибки при синтаксическом анализе XML. Возвращается текстовое сообщение с объяснением ошибки (например: при обновлении требуется версия). Это также может произойти, если вы забудете передать заголовок Content-Length

когда идентификатор пакета правок отсутствует (к сожалению, сообщения об ошибках не совпадают)

когда точка находится за пределами внешнего мира

когда точек слишком много для определенной линии

HTTP status code 409 (Conflict) - text/plain

когда версия предоставленного элемента не соответствует текущей версии элемента в базе данных

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at."

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

HTTP status code 412 (Precondition Failed)

когда на линии есть точки, которые не существуют или не видны (т.е. удалены): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."

когда отношение содержит элементы, которые не существуют или не видны: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

HTTP status code 429 (Too many requests)

когда запрос был заблокирован из-за ограничения скорости

Примечания

• это обновляет ограничивающий прямоугольник пакета правок;
• чтобы избежать проблем с производительностью при обновлении нескольких объектов, настоятельно рекомендуется использовать конечную точку Diff upload. Это также единственный способ гарантировать, что несколько объектов будут обновлены в рамках одной транзакции базы данных;
  • если вы не можете использовать разностную выгрузку и планируете обновить больше элементов, не забудьте сделать это последовательно (не параллельно).

Удалить: DELETE /api/0.6/[node|way|relation]/#id

Ожидает, что допустимое представление XML элемента будет удалено.

Например:

<osm>
	<node id="..." version="..." changeset="..." lat="..." lon="..." />
</osm>

Где идентификатор точки в XML должен совпадать с идентификатором в URL, версия должна соответствовать версии загруженного вами элемента, а пакет правок должен соответствовать идентификатору открытого пакета правок, принадлежащего текущему аутентифицированному пользователю. Допускается, но не обязательно, наличие тегов на элементе, за исключением тегов широты/долготы, которые обязательны, без широты+долготы сервер выдает 400 Bad request.

Ответ сервера

Возвращает номер новой версии с типом содержимого text/plain.

Коды ошибок

HTTP status code 400 (Bad Request) - text/plain

при возникновении ошибок при синтаксическом анализе XML. Возвращается текстовое сообщение с объяснением ошибки.

когда идентификатор пакета правок отсутствует (к сожалению, сообщения об ошибках не совпадают)

когда точка находится за пределами внешнего мира

когда точек слишком много для определенной линии

когда версия предоставленного элемента не соответствует текущей версии элемента в базе данных

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

HTTP status code 409 (Conflict) - text/plain

если соответствующий пакет правок уже был закрыт (либо самим пользователем, либо в результате функции автоматического закрытия). Возвращается сообщение в формате "The changeset #id was closed at #closed_at."

или если пользователь, пытающийся обновить пакет правок, отличается от того, который его создал

HTTP status code 410 (Gone)

если элемент уже был удален

HTTP status code 412 (Precondition Failed)

когда точка все еще используется какой-либо линией: Node #{id} is still used by way #{way.id}.

когда узел все еще является участником отношения: Node #{id} is still used by relation #{relation.id}.

когда линия все еще является участником отношения: Way #{id} still used by relation #{relation.id}.

когда отношение все еще является участником другого отношения: The relation #{id} is used in relation #{relation.id}.

Обратите внимание, что при возврате в результате операции загрузки OsmChange сообщения об ошибках содержат ложное множественное число "s", как в ... still used by ways ...", "... still used by relations ..." , даже если возвращается только 1 идентификатор способа или отношения, поскольку это подразумевает, что может быть возвращено несколько идентификаторов, если удаленный объект был/является участником нескольких родительских объектов, эти идентификаторы разделены запятыми. Обратите внимание, что Rails API и CGIMAP ведут себя несогласованно из-за множественного числа "s".

HTTP status code 429 (Too many requests)

когда запрос был заблокирован из-за ограничения скорости

Примечания

• в более ранних версиях API полезная нагрузка не требовалась. Теперь это необходимо из-за необходимости в идентификаторах пакетов правок и номерах версий;
• чтобы избежать проблем с производительностью при обновлении нескольких объектов, настоятельно рекомендуется использовать конечную точку разностной выгрузки. Кроме того, это единственный способ обеспечить обновление нескольких объектов за одну транзакцию базы данных.

История: GET /api/0.6/[node|way|relation]/#id/history

Извлекает все старые версии элемента, отсортированные по номеру версии от самой старой до самой новой (пример)

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

Версия: GET /api/0.6/[node|way|relation]/#id/#version

Извлекает определенную версию элемента.

Коды ошибок

HTTP status code 403 (Forbidden)

когда версия элемента недоступна (из-за редактирования)

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

Множественная выборка: GET /api/0.6/[nodes|ways|relations]?#parameters

Позволяет пользователю извлекать несколько элементов одновременно.

Параметры

[nodes|ways|relations]=comma separated list

параметр должен быть таким же, как и в URL-адресе (например /api/0.6/nodes?nodes=123,456,789);

номера версий для каждого объекта могут быть дополнительно указаны после строчной буквы "v", например, /api/0.6/nodes?узлы=421586779v1,421586779v2 (в настоящее время поддерживается только в CGImap, используется на osm.org [1] ^GitHub)

Коды ошибок

HTTP status code 400 (Bad Request)

при некорректно сформированном запросе (отсутствуют или неверны параметры)

HTTP status code 404 (Not Found)

если один из элементов не удалось найти (под "не найден" подразумевается, что он никогда не существовал в базе данных или его запрошенная версия была отредактирована, если объект был удален, он будет возвращен с атрибутом visible="false")

HTTP status code 414 (Request-URI Too Large)

если URI был слишком длинным (проверено, что URI содержит >8213 символов или >725 элементов для 10-значных идентификаторов, если не указаны версии)

Примечания

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

Отношения для элемента: GET /api/0.6/[node|way|relation]/#id/relations

Возвращает документ XML, содержащий все (не удаленные) отношения, в которых используется данный элемент.

Примечания

• ошибки нет, если элемент не существует;
• если элемент не существует, или он не используется ни в каких отношениях, возвращается пустой документ XML (кроме элементов <osm>).

Линии для точки: GET /api/0.6/node/#id/ways

Возвращает документ XML, содержащий все (не удаленные) способы использования данной точки.

Примечания

• ошибки нет, если точка не существует;
• если точка не существует, или он никоим образом не используется, возвращается пустой документ XML (кроме элементов <osm>).

Полный: GET /api/0.6/[way|relation]/#id/full

Этот вызов API извлекает линию или отношение и все другие элементы, на которые они ссылаются

• для линий вернет указанную линию, плюс полный код XML всех точек, на которые ссылается эта линия.
• для отношения он вернет следующее значение:
  • само отношение
  • все точки, линии и отношения, которые являются участниками отношения
  • плюс все точки, используемые линиями из предыдущего шага
  • та же самая рекурсивная логика не применяется к отношениям. Это означает: если отношение r1 содержит линию w1 и отношение r2, а w1 содержит точки n1 и n2, а r2 содержит точку n3, то "полный" запрос для r1 даст вам r1, r2, w1, n1 и n2. Только не n3.

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти ни один элемент с заданным идентификатором

HTTP status code 410 (Gone)

если элемент был удален

Редакция: POST /api/0.6/[node|way|relation]/#id/#version/redact?redaction=#redaction_id

Это метод API, изначально созданный для ODbL license change, чтобы скрыть вклады от пользователей, которые не приняли новую CT/licence. В настоящее время он используется DWG для скрытия старых версий элементов, содержащих нарушения конфиденциальности данных или авторских прав. Все запросы API на поиск элемента #version будут возвращать HTTP error 403.

Примечания

• разрешено только для учетных записей OSM с ролью модератора (администраторы DWG и сервера);
• требуется write_redactions области действия OAuth; до сентября 2024 года требовался либо write_api, либо write_redactions, а до декабря 2023 года требовался write_api; эти более старые требования к области действия могут по-прежнему применяться на других серверах на базе веб-сайтов openstreetmap, таких как OpenHistoricalMap;
• идентификатор #redaction_id указан на https://www.openstreetmap.org/redactions;
• более подробную информацию можно найти в источниках;
• это чрезвычайно специализированный запрос

Коды ошибок

HTTP status code 400 (Bad Request)

"Невозможно отредактировать текущую версию элемента, могут быть отредактированы только исторические версии".

Треки GPS

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

Получить точки GPS: Get /api/0.6/trackpoints?bbox=left,bottom,right,top&page=pageNumber

Используйте для получения точек трека GPS, которые находятся внутри заданного ограничивающего прямоугольника (отформатированного в формате GPX).

где

• left - долгота левой (самой западной) стороны ограничивающего прямоугольника;
• bottom - широта нижней (самой южной) стороны ограничивающего прямоугольника;
• right - долгота правой (самой восточной) стороны ограничивающего прямоугольника;
• top - широта верхней (самой северной) стороны ограничивающего прямоугольника;
• pageNumber - указывает, какую группу из 5000 точек, или страницу, следует возвращать. Поскольку команда возвращает не более 5000 точек за раз, этот параметр должен быть увеличен — и команда должна быть отправлена повторно (с использованием того же ограничивающего прямоугольника) — чтобы получить все точки для ограничивающего прямоугольника, содержащего более 5000 точек. Если этот параметр равен 0 (нулю), команда возвращает первые 5000 точек; если он равен 1, команда возвращает 5,001-10,000 точек и т.д.

Максимальная ширина (справа - слева) и высота (сверху - снизу) ограничивающего прямоугольника составляют 0.25 градуса.

Примеры

Извлечь первые 5000 точек для ограничивающего прямоугольника:

https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=0

Извлечь следующие 5000 точек (от 5 001 до 10 000 точек) для того же ограничивающего прямоугольника:

https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=1

Ответ сервера

• этот ответ НЕ заключен в родительский элемент OSM xml;
• формат файла - GPX версии 1.0, который не является текущей версией. Убедитесь, что ваши инструменты поддерживают его.

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.0" creator="OpenStreetMap.org" xmlns="http://www.topografix.com/GPX/1/0">
	<trk>
		<name>20190626.gpx</name>
		<desc>Footpaths near Blackweir Pond, Epping Forest</desc>
		<url>https://api.openstreetmap.org/user/John%20Leeming/traces/3031013</url>
		<trkseg>
			<trkpt lat="51.6616100" lon="0.0534560">
				<time>2019-06-26T14:27:58Z</time>
			</trkpt>
			...
		</trkseg>
		...
	</trk>
	...
</gpx>

Создать: POST /api/0.6/gpx

Также доступно по запросу POST /api/0.6/gpx/create (устарело)

Используйте для загрузки файла GPX или архива файлов GPX. Требуется аутентификация.

В сообщении HTTP, состоящем из нескольких частей (multipart) или содержащем данные формы (form-data), требуются следующие параметры:

Ответ сервера

Число, представляющее идентификатор нового GPX

Коды ошибок

HTTP status code 400 (Bad Request)

когда описание пустое

Обновить: PUT /api/0.6/gpx/#id

Используйте для обновления метаданных в файле GPX. Доступно только для учетной записи владельца. Требуется аутентификация. Текст запроса представляет собой файл xml с той же структурой, что и ответы Скачатьметаданные.

Ответ сервера

Текст ответа будет пустым.

Удалить: DELETE /api/0.6/gpx/#id

Используйте для удаления файла GPX. Доступен только для учетной записи владельца. Требуется аутентификация.

Ответ сервера

Текст ответа будет пустым.

Скачать метаданные: GET /api/0.6/gpx/#id

Также доступно по запросу GET /api/0.6/gpx/#id/details (устарело)

Используйте для доступа к метаданным о файле GPX. Доступно без проверки подлинности, если файл помечен как общедоступный. В противном случае может использоваться только учетной записью владельца и требует проверки подлинности.

Ответ сервера XML

Пример ответа сервера "details":

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server">
	<gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
		<description>PHP upload test</description>
		<tag>test</tag>
		<tag>php</tag>
	</gpx_file>
</osm>

Примечания

• атрибут uid был добавлен в сентябре 2023 ^GitHub.

Ответ сервера JSON

Этот вызов API также поддерживает ответ сервера в формате JSON.

Скачать данные: GET /api/0.6/gpx/#id/data

Используйте для загрузки полного файла GPX. Доступен без проверки подлинности, если файл помечен как общедоступный. В противном случае он доступен только для учетной записи владельца и требует проверки подлинности.

Ответ сервера

Ответом всегда будет файл формата GPX, если вы используете в URL расширение .gpx, или файл XML в недокументированном формате, если вы используете в URL расширение .xml, в противном случае ответом будет именно тот файл, который был загружен.

Примечания

• если ваш запрос относится к архиву с несколькими файлами, ответ при принудительном использовании формата GPX или XML будет состоять из нестандартной простой конкатенации файлов.

Список: GET /api/0.6/user/gpx_files

Используйте, чтобы получить список треков GPX, принадлежащих прошедшему проверку подлинности пользователю: Требуется проверка подлинности.

Обратите внимание, что /user/ - это буквальная часть адреса URL, а не отображаемое имя пользователя или идентификатор пользователя (этот вызов всегда возвращает трек GPX только для текущего аутентифицированного пользователя).

Ответ сервера XML

Ответ аналогичен ответу из Скачать метаданные, за исключением нескольких возможных элементов <gpx_file>. Пример:

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server">
	<gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
		<description>PHP upload test</description>
		<tag>test</tag>
		<tag>php</tag>
	</gpx_file>
	<gpx_file id="836620" name="track.gpx" lat="52.1194" lon="8.61807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:27:31Z">
		<description>PHP upload test 2</description>
		<tag>test</tag>
		<tag>php</tag>
	</gpx_file>
</osm>

Ответ сервера JSON

Этот вызов API также поддерживает ответ в формате JSON.

Методы обработки пользовательских данных

Сведения о пользователе: GET /api/0.6/user/#id

Этот метод API был добавлен в сентябре 2012 года (code).

Вы можете получить домашнее местоположение и отображаемое имя пользователя, используя

Ответ сервера XML

GET /api/0.6/user/#id

возвращает документ XML следующего вида

<osm version="0.6" generator="OpenStreetMap server">
	<user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
		<description></description>
		<company>bitbetter GmbH</company>
		<social-links>
			<link platform="mastodon">https://mastodon.social/@jbpbis</link>
		</social-links>
		<contributor-terms agreed="false"/>
		<img href="http://www.gravatar.com/avatar/somehash"/>
        <roles>
            <moderator/>
        </roles>
		<changesets count="1"/>
		<traces count="0"/>
		<blocks>
			<received count="0" active="0"/>
		    <issued count="68" active="45"/>
		</blocks>
	</user>
</osm>

Ответ сервера JSON

GET /api/0.6/user/#id.json

возвращает документ JSON следующего вида

{
  "version": "0.6",
  "generator": "OpenStreetMap server",
  "user": {
    "id": 12023,
    "display_name": "jbpbis",
    "account_created": "2007-08-16T01:35:56Z",
    "description": "",
    "company": "MyCompany Ltd.",
    "social_links": [
      {
        "url": "https://mastodon.social/@jbpbis",
        "platform": "mastodon"
      }
    ],
    "contributor_terms": {
      "agreed": false
    },
    "img": {
      "href": "https://www.gravatar.com/avatar/somehash"
    },
    "roles": [],
    "changesets": {
      "count": 1
    },
    "traces": {
      "count": 0
    },
    "blocks": {
      "received": {
        "count": 0,
        "active": 0
      }
    }
  }
}

или пустой файл, если пользователь по данному идентификатору не найден.

Примечания

• учётные записи пользователей, внесших изменения, могут быть удалены. Такие пользователи перечислены по адресу https://planet.osm.org/users_deleted/users_deleted.txt

Сведения о нескольких пользователях: GET /api/0.6/users?users=#id1,#id2,...,#idn

Этот метод API был добавлен в июле 2018 года (code).

Вы можете получить подробную информацию о нескольких пользователях с помощью

Ответ сервера XML

GET /api/0.6/users?users=#id1,#id2,...,#idn

возвращает документ XML следующего вида

<osm version="0.6" generator="OpenStreetMap server">
	<user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
		<description></description>
		<contributor-terms agreed="false"/>
		<img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&amp;d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
		<roles>
		</roles>
		<changesets count="1"/>
		<traces count="0"/>
		<blocks>
			<received count="0" active="0"/>
		</blocks>
	</user>
	<user id="210447" display_name="siebh" account_created="2009-12-20T10:11:42Z">
		<description></description>
		<contributor-terms agreed="true"/>
		<roles>
		</roles>
		<changesets count="267"/>
		<traces count="1"/>
		<blocks>
			<received count="0" active="0"/>
		</blocks>
	</user>
</osm>

Ответ сервера JSON

GET /api/0.6/users.json?users=#id1,#id2,...,#idn

возвращает документ JSON следующего вида

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "users": [
  {"user": {"id": 12023, "display_name": "jbpbis", "account_created": "2007-08-16T01:35:56Z", "description": "", "contributor_terms": {"agreed": False}, "roles": [], "changesets": {"count": 1}, "traces": {"count": 0}, "blocks": {"received": {"count": 0, "active": 0}}}},
  {"user": {"id": 210447, "display_name": "siebh", "account_created": "2009-12-20T10:11:42Z", "description": "", "contributor_terms": {"agreed": True}, "roles": [], "changesets": {"count": 363}, "traces": {"count": 1}, "blocks": {"received": {"count": 0, "active": 0}}}}
 ]
}

или пустой файл, если пользователь по данному идентификатору не найден.

Примечания

Начиная с Pull request 4203 (запущен 26 августа 2023 г.), оба варианта конечной точки пользователей, основанные на XML и JSON, будут пропускать всех несуществующих/приостановленных/удаленных пользователей, вместо того, чтобы сообщать о ранее недокументированной ошибке HTTP 404 error.

Сведения о вошедшем в систему пользователе: GET /api/0.6/user/details

Вы можете получить домашнее местоположение и отображаемое имя пользователя, используя

Ответ сервера XML

GET /api/0.6/user/details

возвращает документ XML следующего вида

<osm version="0.6" generator="OpenStreetMap server">
	<user display_name="Max Muster" account_created="2006-07-21T19:28:26Z" id="1234">
		<contributor-terms agreed="true" pd="true"/>
		<img href="https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"/>
		<roles></roles>
		<changesets count="4182"/>
		<traces count="513"/>
		<blocks>
			<received count="0" active="0"/>
		</blocks>
		<home lat="49.4733718952806" lon="8.89285988577866" zoom="3"/>
		<description>The description of your profile</description>
		<languages>
			<lang>de-DE</lang>
			<lang>de</lang>
			<lang>en-US</lang>
			<lang>en</lang>
		</languages>
		<messages>
			<received count="1" unread="0"/>
			<sent count="0"/>
		</messages>
	</user>
</osm>

Ответ сервера JSON

GET /api/0.6/user/details.json

возвращает документ JSON следующего вида

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "user": {
  "id": 1234,
  "display_name": "Max Muster",
  "account_created": "2006-07-21T19:28:26Z",
  "description": "The description of your profile",
  "contributor_terms": {"agreed": True, "pd": True},
  "img": {"href": "https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"},
  "roles": [],
  "changesets": {"count": 4182},
  "traces": {"count": 513},
  "blocks": {"received": {"count": 0, "active": 0}},
  "home": {"lat": 49.4733718952806, "lon": 8.89285988577866, "zoom": 3},
  "languages": ["de-DE", "de", "en-US", "en"],
  "messages": {"received": {"count": 1, "unread": 0},
  "sent": {"count": 0}}
 }
}

Раздел messages доступен с середины 2013 года. Он содержит основные данные о полученных, отправленных и непрочитанных сообщениях osm.

Предпочтения вошедшего в систему пользователя: GET|PUT|DELETE /api/0.6/user/preferences

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

Вы можете получить список текущих настроек с помощью

Ответ сервера XML

GET /api/0.6/user/preferences

возвращает документ XML следующего вида

<osm version="0.6" generator="OpenStreetMap server">
	<preferences>
		<preference k="somekey" v="somevalue" />
		...
	</preferences>
</osm>

Ответ сервера JSON

GET /api/0.6/user/preferences.json

возвращает документ JSON следующего вида

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "preferences": {"somekey": "somevalue, ...}
}

Примеры

PUT /api/0.6/user/preferences

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

GET /api/0.6/user/preferences/[your_key] (без скобок)

Возвращает строку со значением этого предпочтения.

PUT /api/0.6/user/preferences/[your_key] (без скобок)

Установит значение одного предпочтения в строку, передаваемую в качестве содержимого запроса.

PUT /api/0.6/user/preferences/[your_key]

в этом случае полезная нагрузка запроса должна содержать только значение предпочтения, т.е. не быть отформатированной в формате XML.

Вызов PUT возвращает ответ HTTP response code 406 (not acceptable), если один и тот же ключ встречается более одного раза, и ответ HTTP response code 413 (request entity too large), если вы пытаетесь загрузить более 150 предпочтений одновременно. Размер ключа и значения ограничен 255 символами.

Одна запись о предпочтениях может быть удалена с помощью

DELETE /api/0.6/user/preferences/[your_key]

API для заметок на карте

Обеспечивает доступ к функции notes, которая позволяет пользователям добавлять текстовые заметки "post-it" с географической привязкой. Изначально этой функции не было в API версии 0.6, и она была добавлена позже (23.04.2013 в commit 0c8ad2f86edefed72052b402742cadedb0d674d9). Поскольку это было задумано как совместимая замена API OpenStreetBugs , существует множество особенностей, связанных с тем, как работают другие части API OSM.

Извлечение данных заметок с помощью ограничивающего прямоугольника: GET /api/0.6/notes

Возвращает существующие примечания в указанном ограничивающем прямоугольнике. Примечания будут упорядочены по дате их последнего изменения, самое последнее будет первым. Список заметок может быть возвращен в нескольких различных формах (например, в виде исполняемого файла JavaScript, XML, RSS, JSON и GPX) в зависимости от расширения файла.

Примечания: формат XML, возвращаемый API, отличается от столь же недокументированного формата, используемого для файлов формата "osn", доступного по адресу planet.openstreetmap.org, а также в качестве выходных данных JOSM и Vespucci.

URL: https://api.openstreetmap.org/api/0.6/notes?bbox=left,bottom,right,top (пример)

Возвращаемый тип: application/xml

Вы можете указать формат, в котором вы хотите получать результаты, указав расширение файла. Например, чтобы получить результаты в формате JSON. В настоящее время поддерживаются форматы RSS, XML, JSON и GPX.

Свойства комментария [uid, user, user_url] будут опущены, если комментарий был анонимным.

Ответ сервера XML

GET /api/0.6/notes

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
	<note lon="0.1000000" lat="51.0000000">
		<id>16659</id>
		<url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659</url>
		<comment_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment</comment_url>
		<close_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close</close_url>
		<date_created>2019-06-15 08:26:04 UTC</date_created>
		<status>open</status>
		<comments>
			<comment>
				<date>2019-06-15 08:26:04 UTC</date>
                <uid>1234</uid>
                <user>userName</user>
                <user_url>https://master.apis.dev.openstreetmap.org/user/userName</user_url>
				<action>opened</action>
				<text>ThisIsANote</text>
				<html>&lt;p&gt;ThisIsANote&lt;/p&gt;</html>
			</comment>
			...
		</comments>
	</note>
	...
</osm>

Ответ сервера JSON

GET /api/0.6/notes.json

{
 "type": "FeatureCollection",
 "features": [
  {
   "type": "Feature",
   "geometry": {"type": "Point", "coordinates": [0.1000000, 51.0000000]},
   "properties": {
    "id": 16659,
    "url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659.json",
    "comment_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment.json",
    "close_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close.json",
    "date_created": "2019-06-15 08:26:04 UTC",
    "status": "open",
    "comments": [
     {"date": "2019-06-15 08:26:04 UTC", "uid": 1234, "user": "userName", "user_url": "https://master.apis.dev.openstreetmap.org/user/userName", "action": "opened", "text": "ThisIsANote", "html": "<p>ThisIsANote</p>"},
     ...
    ]
   }
  }
 ]
}

Коды ошибок

HTTP status code 400 (Bad Request)

когда нарушается какой-либо из пределов

Прочитать: GET /api/0.6/notes/#id

Возвращает существующую заметку с заданным идентификатором. Выходные данные могут быть в нескольких форматах (например, XML, RSS, JSON или GPX) в зависимости от расширения файла.

URL: https://api.openstreetmap.org/api/0.6/notes/#id (XML, JSON)

Возвращаемый тип: application/xml

Коды ошибок

HTTP status code 404 (Not Found)

если не удалось найти заметку с указанным идентификатором. Это значение возвращается только для еще не существующих заметок.

HTTP status code 410 (Gone)

если заметка была скрыта модератором. Обратите внимание, что сообщение об ошибке The note with the id nnnnnnnnn has already been deleted вводит в заблуждение, поскольку на самом деле не модераторы не могут удалять/скрывать заметки с помощью API.

Создать новую заметку: POST /api/0.6/notes

Ответ сервера XML

URL: https://api.openstreetmap.org/api/0.6/notes?lat=51.00&lon=0.1&text=ThisIsANote (используйте Postman или аналогичные инструменты для тестирования конечной точки - обратите внимание, что это должен быть запрос POST)

Возвращаемый тип: application/xml

Будет возвращен файл XML с подробной информацией о заметке

Ответ сервера JSON

URL: https://api.openstreetmap.org/api/0.6/notes.json

Содержание тела: {"lat":51.00, "lon": 0.1&, "text":"This is a note\n\nThis is another line"}

Возвращаемый тип: application/json

Будет возвращен файл JSON с подробной информацией о заметке

Параметры

Если запрос сделан от имени аутентифицированного пользователя, заметка привязывается к этой учетной записи пользователя. Если используемый токен доступа OAuth не имеет разрешения allow_write_notes, она создается как анонимная заметка.

Коды ошибок

HTTP status code 400 (Bad Request)

если текстовое поле отсутствовало

HTTP status code 404 (Not found)

применимо, если запрос не является запросом HTTP POST

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP POST

Создать новый комментарий: POST /api/0.6/notes/#id/comment

Добавьте новый комментарий к заметке #id

URL: https://api.openstreetmap.org/api/0.6/notes/#id/comment?text=ThisIsANoteComment (используйте Postman или аналогичные инструменты для тестирования конечной точки - обратите внимание, что это должен быть запрос POST)

Возвращаемый тип: application/xml

С 28 августа 2019 года этот запрос необходимо выполнять от имени аутентифицированного пользователя.

Ответ будет содержать соответствующий файл XML.

Коды ошибок

HTTP status code 400 (Bad Request)

если текстовое поле отсутствовало

HTTP status code 404 (Not found)

если заметка с таким идентификатором недоступна. Должна выполняться только для еще не существующих заметок.

также применимо, если запрос не является запросом HTTP POST

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP POST

HTTP status code 409 (Conflict)

когда заметка закрыта

HTTP status code 410 (Gone)

если заметка была скрыта модератором. Обратите внимание, что сообщение об ошибке "The note with the id nnnnnnnnn has already been deleted" вводит в заблуждение, поскольку на самом деле не модераторы не могут удалять/скрывать заметки через API.

Закрыть: POST /api/0.6/notes/#id/close

Закрыть заметку как исправленную.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/close?text=Comment (используйте Postman или аналогичные инструменты для тестирования конечной точки - обратите внимание, что это должен быть запрос POST)

Возвращаемый тип: application/xml

Этот запрос должен быть выполнен от имени аутентифицированного пользователя.

Коды ошибок

HTTP status code 404 (Not Found)

если не удалось найти заметку с указанным идентификатором. Должно происходить только для еще не существующих заметок.

это также применимо, если запрос не является запросом HTTP POST

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP POST

HTTP status code 409 (Conflict)

при закрытии уже закрытой заметки

HTTP status code 410 (Gone)

если заметка была скрыта модератором. Обратите внимание, что сообщение об ошибке "The note with the id nnnnnnnnn has already been deleted" вводит в заблуждение, поскольку на самом деле не модератор не может удалить/крыть заметки с помощью API.

Снова открыть: POST /api/0.6/notes/#id/reopen

Снова открыть закрытую заметку.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/reopen?text=Comment (используйте Postman или аналогичные инструменты для тестирования конечной точки)

Возвращаемый тип: application/xml

Этот запрос должен быть выполнен от имени аутентифицированного пользователя.

Коды ошибок

HTTP status code 404 (Not Found)

когда не удалось найти заметку с указанным идентификатором

это также применимо, если запрос не является запросом HTTP POST

HTTP status code 405 (Method Not Allowed)

если запрос не является запросом HTTP POST

HTTP status code 409 (Conflict)

при повторном открытии уже открытой заметки

HTTP status code 410 (Gone)

при повторном открытии удаленной заметки

Скрыть: DELETE /api/0.6/notes/#id

Скрыть (удалить) заметку.

URL: https://api.openstreetmap.org/api/0.6/notes/#id?text=Comment (используйте Postman или аналогичные инструменты для тестирования конечной точки)

Возвращаемый тип: application/xml

Этот запрос должен быть выполнен от имени аутентифицированного пользователя с ролью модератора.

Используйте запрос Reopen, чтобы снова сделать заметку видимой.

Коды ошибок

HTTP status code 403 (Forbidden)

если пользователь не является модератором

HTTP status code 404 (Not Found)

когда не удалось найти заметку с указанным идентификатором

HTTP status code 410 (Gone)

при скрытии заметки, которая уже скрыта

Подписаться: POST /api/0.6/notes/#id/subscription

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

URL: https://api.openstreetmap.org/api/0.6/notes/:id/subscription

Возвращаемый тип: (пустой ответ)

Этот запрос должен быть выполнен от имени аутентифицированного пользователя.

Коды ошибок

HTTP status code 404 (Not Found)

если заметка не существует

HTTP status code 409 (Conflict)

если пользователь уже подписан на эту заметку

Отписаться: DELETE /api/0.6/notes/#id/subscription

Отказаться от подписки на обсуждение заметки

URL: https://api.openstreetmap.org/api/0.6/notes/:id/subscription

Возвращаемый тип: (пустой ответ)

Этот запрос должен быть выполнен от имени аутентифицированного пользователя.

Коды ошибок

HTTP status code 404 (Not Found)

если заметка не существует или пользователь не подписан на эту заметку

Поиск заметок: GET /api/0.6/notes/search

Возвращает заметки, соответствующие указанному запросу. Если запрос не задан, возвращаются самые последние обновленные заметки.

Результат может быть закодирован в нескольких различных форматах (XML, RSS, JSON или GPX), в зависимости от предоставленного расширения файла.

URL: https://api.openstreetmap.org/api/0.6/notes/search

Примеры

Смотреть последние обновления заметок по всему миру:

 https://api.openstreetmap.org/api/0.6/notes/search

Найти текст в комментариях:

 https://api.openstreetmap.org/api/0.6/notes/search?q=business%20spam

Просмотр заметок одного пользователя:

 https://api.openstreetmap.org/api/0.6/notes/search?user=123

Поиск самых старых заметок вблизи острова Null:

 https://api.openstreetmap.org/api/0.6/notes/search?bbox=-1%2C-1%2C1%2C1&sort=created_at&order=oldest&closed=-1&limit=20

Коды ошибок

HTTP status code 400 (Bad Request)

когда нарушается какой-либо из этих пределов

Канал RSS: GET /api/0.6/notes/feed

Получить канал RSS для заметок в пределах определенной области.

URL: https://api.openstreetmap.org/api/0.6/notes/feed

Возвращаемый тип: application/xml

Блокировка пользователей

Создать: POST /api/0.6/user_blocks

Параметры

Коды ошибок

HTTP status code 400 (Bad Request)

если какой-либо из обязательных параметров отсутствует или имеет недопустимое значение

HTTP status code 404 (Not found)

когда заблокированный пользователь не найден

Прочитать: GET /api/0.6/user_blocks/#id

Ответ сервера XML

GET /api/0.6/user_blocks/#id

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
<user_block id="96" created_at="2025-01-21T23:23:50Z" updated_at="2025-01-21T23:24:16Z" ends_at="2025-01-21T23:24:16Z" needs_view="false">
  <user uid="3" user="fakeuser1"/>
  <creator uid="5" user="fakemod1"/>
  <revoker uid="5" user="fakemod1"/>
  <reason>reason text

more reason text</reason>
</user_block>
</osm>

Ответ сервера JSON

GET /api/0.6/user_blocks/#id.json

{
	"version":"0.6",
	"generator":"OpenStreetMap server",
	"copyright":"OpenStreetMap and contributors",
	"attribution":"http://www.openstreetmap.org/copyright",
	"license":"http://opendatacommons.org/licenses/odbl/1-0/",
	"user_block":{
		"id":96,
		"created_at":"2025-01-21T23:23:50Z",
		"updated_at":"2025-01-21T23:24:16Z",
		"ends_at":"2025-01-21T23:24:16Z",
		"needs_view":false,
		"user":{"uid":3,"user":"fakeuser1"},
		"creator":{"uid":5,"user":"fakemod1"},
		"revoker":{"uid":5,"user":"fakemod1"},
		"reason":"reason text\r\n\r\nmore reason text"
	}
}

Список активных блокировок: GET /api/0.6/user/blocks/active

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

Ответ сервера XML

GET /user/blocks/active

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
<user_block id="101" created_at="2025-02-22T02:11:55Z" updated_at="2025-02-22T02:11:55Z" ends_at="2025-02-22T03:11:55Z" needs_view="true">
  <user uid="5" user="fakemod1"/>
  <creator uid="115" user="fakemod2"/>
</user_block>
<user_block id="100" created_at="2025-02-22T02:11:10Z" updated_at="2025-02-22T02:11:10Z" ends_at="2025-02-22T02:11:10Z" needs_view="true">
  <user uid="5" user="fakemod1"/>
  <creator uid="115" user="fakemod2"/>
</user_block>
...
</osm>

Пустой элемент <osm> указывает на отсутствие активных блокировок.

Ответ сервера JSON

GET /user/blocks/active.json

{
	"version":"0.6","generator":"OpenStreetMap server","copyright":"OpenStreetMap and contributors","attribution":"http://www.openstreetmap.org/copyright","license":"http://opendatacommons.org/licenses/odbl/1-0/",
	"user_blocks":[
		{
			"id":101,
			"created_at":"2025-02-22T02:11:55Z",
			"updated_at":"2025-02-22T02:11:55Z",
			"ends_at":"2025-02-22T03:11:55Z",
			"needs_view":true,
			"user":{"uid":5,"user":"fakemod1"},
			"creator":{"uid":115,"user":"fakemod2"}
		},
		{
			"id":100,
			"created_at":"2025-02-22T02:11:10Z",
			"updated_at":"2025-02-22T02:11:10Z",
			"ends_at":"2025-02-22T02:11:10Z",
			"needs_view":true,
			"user":{"uid":5,"user":"fakemod1"},
			"creator":{"uid":115,"user":"fakemod2"}
		},
		...
	]
}

Пустой массив user_blocks указывает на отсутствие активных блокировок.

Когда API НЕЛЬЗЯ использовать

Для сценариев массовой загрузки или модификации данных прямое использование API может оказаться неподходящим механизмом. Современная версия создания скрипта массовой загрузки или модификации заключается в создании набора изменений, загрузке его в редактор, подобный JOSM, и проверке работы перед фиксацией. Вы также можете использовать API для загрузки пакета правок атомарным способом. Смотрите также: Изменения форматов файлов, Import

API в первую очередь предназначен для редактирования. Для целей или проектов, доступных только для чтения, смотрите Политика использования API.

Семантическое управление версиями

На момент первого развертывания семантическое управление версиями (с меньшим номером версии) не было устоявшейся концепцией. В результате API не соответствует этой схеме. Многие приложения не смогли бы корректно обрабатывать незначительные изменения номера версии, поэтому не предпринимается никаких попыток добавить его, хотя текущую версию можно считать 0.6.9.

Читать далее

• Люди, создающие клиентские программы, видят OSM_Protocol_Version_0.6 (Archive)#Changes_in_related_software
• Люди, интересующиеся базой данных, видят OSM_Protocol_Version_0.6 (Archive)#Database_improvements
• возможные ошибки API
• Category:OSM API library - библиотеки или языковые оболочки для некоторых или всех API OpenStreetMap, потенциально полезные для людей, пишущих редакторы

Рекомендации