ES:API v0.6

From OpenStreetMap Wiki
Jump to navigation Jump to search
API v0.6 - Other languages

API v0.6 es la versión actual de la API de edición de OSM originalmente implementada del 17 al 21 de abril de 2009.

Esta página y la API se han ampliado y actualizado varias veces desde abril de 2009:

Cambios futuros/planificados: (ninguno)

Información general

Tenga en cuenta que esta no es documentación oficial[1]. El comportamiento documentado aquí puede cambiar en el futuro[2].

El código que impulsa la API se puede encontrar en GitHub en openstreetmap/openstreetmap-website/tree/master/app/controllers/api GitHub.

Algunas de las llamadas API en osm.org son manejadas por CGImap y su código fuente también está disponible en GitHub en zerebubuth/openstreetmap-cgimap GitHub

Esta API de edición se basa en las ideas de la API RESTful. Para obtener más información sobre las API RESTful, consulte la página de Transferencia de estado representacional de Wikipedia.

La API es el componente del servidor al que se dirigen las solicitudes REST. Las solicitudes REST toman la forma de mensajes HTTP GET, PUT, POST y DELETE. Cualquier carga útil está en formato XML, utilizando el tipo MIME "text/xml" y codificación de caracteres UTF-8, y puede comprimirse en la capa HTTP si el cliente indica a través del encabezado HTTP "Accept" que puede manejar mensajes comprimidos.

Las solicitudes de modificación de la base de datos se autorizan mediante "OAuth". Las solicitudes de lectura no requieren autorización (excepto los datos del usuario).

Cambios entre API v0.5 y API v0.6

Para descargar datos para otros fines que no sean la edición, consulte Descarga de datos; probablemente utilizará Overpass API (quizás con Overpass turbo), Planet.osm o extractos.

URL + autenticación

Para obtener más información sobre el uso de OAuth, consulte también el artículo principal sobre OAuth

Actualmente se puede acceder a la API mediante la siguiente URL: https://api.openstreetmap.org/

Al probar su software con la API, debería considerar usar https://master.apis.dev.openstreetmap.org/ en lugar de la API activa. Su cuenta para el servicio activo no está en la misma base de datos, por lo que probablemente necesite un nuevo nombre de usuario y contraseña para el servicio de prueba; visite esa página en un navegador para registrarse.

Todas las llamadas a la API que actualicen, creen o eliminen datos deben ser realizadas por un usuario autenticado y autorizado. La autenticación funciona mediante OAuth 2.0.

Ámbitos requeridos para Oauth 2.0

Los ámbitos OAuth necesarios para poder utilizar la API completa v0.6 son:

  • preferencias de lectura
  • preferencias_de_escritura
  • escritura_api
  • leer_gpx
  • escribir_gpx
  • escribir_notas
  • write_diary (ámbito admitido por OAuth2 pero no requerido por la API v0.6)
  • escribir_redacciones
  • consumir_mensajes
  • enviar_mensajes

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Si está accediendo a la versión cgimap de la API, se devolverá este código de error cuando OAuth falle con una "Solicitud de OAuth incorrecta".
Código de estado HTTP 401 (No autorizado)
El inicio de sesión no fue exitoso.
Código de estado HTTP 403 (Prohibido)
El inicio de sesión fue exitoso pero el usuario no puede realizar la operación.
Es posible que el usuario haya sido bloqueado o que la aplicación OAuth no haya recibido los permisos necesarios. La aplicación debe mostrar el mensaje de error (que se traducirá si es necesario) y, si tiene una interfaz de usuario para el usuario final, proporcionar una forma sencilla de acceder a openstreetmap.org y ver los mensajes que aparecen allí.

Elementos

Existen llamadas API para crear, leer, actualizar y eliminar los tres elementos básicos que conforman los datos del mapa para OpenStreetMap. Cada una de ellas devuelve o espera los datos de los elementos en formato XML.

Conjuntos de cambios

Cada modificación de uno o más de los elementos debe hacer referencia a un conjunto de cambios abierto.

Etiquetas

Cada elemento y conjunto de cambios puede tener cualquier cantidad de etiquetas. Una etiqueta es un par de cadenas Unicode de clave-valor de hasta 255 caracteres Unicode completos (no bytes) cada una.

Longitudes máximas de cadena

La implementación actual de Rails y CGImap de la API limita la longitud de las cadenas de clave y valor para las etiquetas de objetos, conjuntos de cambios y preferencias de usuario, y los roles de miembros de relación, a un máximo de 255 caracteres Unicode UTF-8.

Nota: el límite es realmente 255 y NO 256 caracteres Unicode.

Identificación confiable de usuarios

La API v0.5 anterior solo devolvía el nombre para mostrar del usuario. El usuario puede actualizarlo en cualquier momento y no se almacena ningún historial de cambios de nombre para mostrar. Esto significa que no había forma de identificar de manera confiable qué usuario realizó un cambio específico. La API v0.6 incluye el ID numérico de usuario de la cuenta además del nombre para mostrar. Por ejemplo, 

<nodo id="68" ... usuario="fred" uid="123" />

Para ello, el usuario debe haber hecho públicas sus modificaciones. El ID de usuario de los usuarios que hayan realizado cambios anónimos anteriormente no será visible. De acuerdo con una recomendación de la Junta Directiva de la Fundación OpenStreetMap, las modificaciones anónimas ya no están permitidas.

Números de versión/bloqueo optimista

El volcado del planeta, las diferencias y las llamadas API para los elementos devolverán un atributo "versión" para cada "Nodo", "Camino" y "Relación". 

<nodo id="68" ... versión="12" />

Estos números de versión se utilizan para el "bloqueo optimista". Para cargar una nueva versión de un objeto, el cliente deberá proporcionar la versión del objeto que está modificando. Si la versión proporcionada no es la misma que la versión actual del servidor, se devolverá un error (código de estado HTTP 409: Conflicto). Esto significa que cualquier cliente que esté actualizando datos deberá guardar los números de versión de los datos originales. Un elemento se puede actualizar varias veces durante un conjunto de cambios y su número de versión se incrementa cada vez, por lo que puede haber varias "versiones históricas" de un solo elemento para un conjunto de cambios.

Además, los clientes ahora pueden solicitar versiones específicas de un elemento.

Los números de versión siempre comenzarán en "1" y aumentarán en 1 cada vez que se modifique un elemento. Sin embargo, los clientes no deben confiar en el aumento en 1 al actualizar un elemento, sino que deben recuperar el nuevo número de versión de la respuesta del servidor.

Formato XML

Artículo principal: XML de OSM

Cada respuesta XML del servidor se envuelve en un elemento <osm> a menos que se especifique lo contrario (por ejemplo, para cargas de diferencias o descargas de conjuntos de cambios). En la mayoría de los ejemplos posteriores, este envoltorio se omite. 

<osm version="0.6" generador="Servidor OpenStreetMap">
	...
	...
</osm>

Cada llamada a la API también debe estar envuelta en un elemento <osm>, pero los atributos version y generator pueden omitirse.

Formato JSON

Artículo principal: OSM JSON

El formato JSON de la API de OSM se basa en (pero no es completamente compatible con) la descripción del formato JSON de la API de Overpass y es compatible con los siguientes puntos finales:

  • Recuperación de datos del mapa mediante el cuadro delimitador: GET /api/0.6/map
  • Lectura: GET /api/0.6/[nodo|vía|relación]/#id
  • Historial: GET /api/0.6/[nodo|vía|relación]/#id/history
  • Versión: GET /api/0.6/[nodo|vía|relación]/#id/#versión
  • Obtención múltiple: GET /api/0.6/[nodes|ways|relations]?#parameters
  • Relaciones para el elemento: GET /api/0.6/[node|way|relation]/#id/relations
  • Formas para el nodo: GET /api/0.6/node/#id/ways
  • Completo: GET /api/0.6/[way|relation]/#id/full

Además, los siguientes puntos finales admiten el formato JSON:

  • Recuperación de versiones de API: GET /api/versions
  • Recuperación de capacidades de API: GET /api/capabilities y GET /api/0.6/capabilities
  • Recuperando permisos: GET /api/0.6/permissions
  • Métodos para datos de usuario
    • Detalles de un usuario: GET /api/0.6/user/#id
    • Detalles de varios usuarios: GET /api/0.6/users?users=#id1,#id2,...,#idn
    • Detalles del usuario conectado: GET /api/0.6/user/details
    • Preferencias del usuario conectado: GET /api/0.6/preferences
  • API de notas de mapas
    • Recuperación de datos de notas mediante el cuadro delimitador: GET /api/0.6/notes
    • Leer: GET /api/0.6/notes/#id
    • Crear una nueva nota: POST /api/0.6/notes
    • Buscar notas: GET /api/0.6/notes/search
  • Conjuntos de cambios
    • Consulta: GET /api/0.6/changesets
    • Leer: GET /api/0.6/changeset/#id?include_discussion=true
    • Suscribirse: POST /api/0.6/changeset/#id/subscribe (respuesta JSON)
    • Cancelar suscripción: POST /api/0.6/changeset/#id/unsubscribe (respuesta JSON)
    • Comentario: POST /api/0.6/changeset/#id/comment (respuesta JSON)
    • Ocultar comentario del conjunto de cambios: POST /api/0.6/changeset/comment/#comment_id/hide (respuesta JSON)
    • Mostrar comentario del conjunto de cambios: POST /api/0.6/changeset/comment/#comment_id/unhide (respuesta JSON)

Para solicitar el formato JSON, configure el encabezado HTTP Accept en application/json o use un sufijo de URL .json.

(Problema de Github)

Falsificando los métodos HTTP correctos

A partir de febrero de 2024, ya no se admite la falsificación del método de solicitud HTTP mediante el suministro de un encabezado X_HTTP_METHOD_OVERRIDE. No se sabe cuándo se eliminó esta función.

Errores internos al generar una respuesta

En el improbable caso de que se produzca un error interno al generar la respuesta a una llamada de API, se insertará un elemento error. El procesamiento posterior se detiene en este punto.

Aunque el código de retorno HTTP sea 200 y la respuesta sea sintácticamente correcta, el mensaje estará incompleto y las aplicaciones de edición DEBEN descartarlo. Para un análisis más detallado, las aplicaciones de edición DEBEN informar un error interno de API al usuario, junto con el mensaje de error devuelto por la llamada a la API.


Ejemplo de carga útil XML que contiene un elemento "error" 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generator="CGImap 0.8.7 (26234 ubuntu)" copyright="OpenStreetMap y colaboradores" 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="bicicleta" v="use_sidepath"/>
  <tag k="autopista" v="secundaria"/>
  <tag k="velocidad máxima" v="50"/>
  <tag k="nombre" v="Bunderstraat"/>
  <tag k="referencia_antigua" v="N586"/>
  <tag k="superficie" v="asfalto"/>
 </way>
 <error>No hay coincidencia en el tamaño de la clave y el valor de las etiquetas</error>
</osm>


Ejemplo de carga útil JSON que contiene un elemento "error" 

{
"versión": "0.6",
"generador": "CGImap 0.8.7 (22730 ubuntu)",
"copyright": "OpenStreetMap y colaboradores",
"atribución": "http://www.openstreetmap.org/copyright",
"licencia": "http://opendatacommons.org/licenses/odbl/1-0/",
"elementos": [
    {
"tipo": "camino",
"identificación": 4000392204,
"marca de tiempo": "2022-07-26T20:56:27Z",
"versión": 1,
"conjunto de cambios": 1874689,
"usuario": "mmd2",
"uido": 1,
"nodos": [
        5004686582,
        5004686236,
        5004686540,
        5004686705,
        5004686546,
        5004686468,
        5004686472
      ],
"etiquetas": {
"bicicleta": "use_sidepath",
"autopista": "secundaria",
"velocidad máxima": "50",
"nombres": "Bunderstraat",
"referencia antigua": "N586",
"superficie": "asfalto"
      }
    },
    {
"error": "No hay coincidencia en el tamaño de la clave y el valor de las etiquetas"
    }
  ]
}

Llamadas API

Misceláneos

Versiones de API disponibles: GET /api/versions

Devuelve una lista de versiones de API compatibles con esta instancia.

XML de respuesta

OBTENER /api/versiones 

<?xml versión="1.0" encoding="UTF-8"?>
<osm generator="Servidor OpenStreetMap" copyright="OpenStreetMap y colaboradores" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
    <api>
        <versión>0.6</versión>
    </api>
</oms>

Respuesta JSON

OBTENER /api/versions.json 

{
 "versión": "0.6",
 "generador": "servidor OpenStreetMap",
 "api": {
  "versiones": ["0.6"]
 }
}

Capacidades: GET /api/capabilities

También disponible como: GET /api/0.6/capabilities.

Esta llamada API está destinada a proporcionar información sobre las capacidades y limitaciones de la API actual.

Respuesta

Devuelve un documento XML (tipo de contenido text/xml) 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generator="Servidor OpenStreetMap" copyright="OpenStreetMap y colaboradores" 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>

Tenga en cuenta que los valores reales devueltos pueden cambiar en cualquier momento y este documento XML solo sirve como ejemplo.

  • Copyright, atribución y licencia: referencia a la información legal

API:

  • versión mínima y máxima son las versiones de llamada API que el servidor aceptará.
  • área máximo es el área máxima en grados cuadrados que se puede consultar mediante llamadas API.
  • tracepoints per_page es la cantidad máxima de puntos en un solo rastreo GPS. (Posiblemente incorrecto)
  • waynodes maximum es el número máximo de nodos que una vía puede contener.
  • relationmembers maximum es el número máximo de miembros que puede contener una relación. (agregado en febrero de 2022)
  • changesets maximum_elements es el número máximo de nodos, formas y relaciones combinados que se pueden incluir en un conjunto de cambios.
  • changesets default_query_limit y maximum_query_limit son los valores predeterminados y máximos del parámetro limit de las consultas de conjuntos de cambios. (agregado en agosto de 2023 GitHub)
  • notas default_query_limit y maximum_query_limit son los valores predeterminados y máximos del parámetro de límite de las notas consultas de cuadro delimitador y búsqueda. (agregado en agosto de 2023 GitHub)
  • El elemento status devuelve online, readonly o offline para cada una de las bases de datos, API y API GPX. El campo database es informativo y los campos api/gpx indican si un cliente debe esperar que las solicitudes de lectura y escritura funcionen (online), que solo funcionen las solicitudes de lectura (readonly) o que no funcione ninguna solicitud (offline).

Política:

  • La lista negra de imágenes incluye todas las fuentes aéreas y cartográficas que no están permitidas para el uso en OSM debido a los derechos de autor. Los editores no deben mostrar estos recursos como capa de fondo.

Notas

  • Actualmente, existen versiones de esta llamada con versiones (/api/0.6/capabilities) y sin versiones (/api/capabilities). La versión sin versiones está obsoleta GitHub a favor de verificar primero las versiones disponibles y luego acceder a las capacidades de una versión en particular.
  • Los identificadores de elementos y miembros de relación actualmente dependen de la implementación y están limitados a números enteros con signo de 64 bits, esto no debería ser un problema :-).

Recuperación de datos del mapa mediante el cuadro delimitador: GET /api/0.6/map

El siguiente comando devuelve:

  • Todos los nodos que están dentro de un cuadro delimitador determinado y cualquier relación que haga referencia a ellos.
  • Todas las vías que hacen referencia al menos a un nodo que está dentro de un cuadro delimitador determinado, cualquier relación que haga referencia a ellas [las vías] y cualquier nodo fuera del cuadro delimitador al que las vías puedan hacer referencia.
  • Todas las relaciones que hacen referencia a uno de los nodos, vías o relaciones incluidas debido a las reglas anteriores. (No se aplica de forma recursiva, consulte la explicación a continuación).

OBTENER /api/0.6/map?bbox=izquierda,abajo,derecha,arriba

dónde:

  • left es la longitud del lado izquierdo (más occidental) del cuadro delimitador.
  • bottom es la latitud del lado inferior (más al sur) del cuadro delimitador.
  • right es la longitud del lado derecho (más oriental) del cuadro delimitador.
  • top es la latitud del lado superior (más al norte) del cuadro delimitador.

Tenga en cuenta que, si bien este comando devuelve aquellas relaciones que hacen referencia a los nodos y vías mencionados anteriormente, lo inverso no es cierto: no devuelve (necesariamente) todos los nodos y vías a los que hacen referencia estas relaciones. Esto evita conjuntos de resultados irrazonablemente grandes. Por ejemplo, imagine el caso en el que:

  • Existe una relación llamada "Inglaterra" que hace referencia a cada nodo de Inglaterra.
  • Los nodos, formas y relaciones se recuperan para un cuadro delimitador que cubre una pequeña porción de Inglaterra.

Si bien el resultado incluiría los nodos, las vías y las relaciones especificadas en las reglas del comando, incluida la relación "Inglaterra", (por casualidad) "no" incluiría "todos" los nodos y vías de Inglaterra. Si se desea, los nodos y vías a los que hace referencia la relación "Inglaterra" se pueden recuperar por sus respectivos identificadores.

Tenga en cuenta también que las vías que intersecan el cuadro delimitador pero no tienen nodos dentro del mismo no se devolverán.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando se excede alguno de los límites de nodos/vías/relaciones, en particular si la llamada retornaría más de 50.000 nodos. Consulte más arriba otros usos de este código.
Código de estado HTTP 509 (Límite de ancho de banda excedido)
"Error: ha descargado demasiados datos. Inténtelo de nuevo más tarde". Consulte las Preguntas frecuentes para desarrolladores.


Recuperando permisos: GET /api/0.6/permissions

Devuelve los permisos otorgados a la conexión API actual.

  • Si el cliente API no está autorizado, se devolverá una lista vacía de permisos.
  • Si el cliente API utiliza autenticación básica, la lista de permisos contendrá todos los permisos.
  • Si el cliente API utiliza OAuth 1.0a, la lista contendrá los permisos realmente otorgados por el usuario.
  • Si el cliente API usa OAuth 2.0, la lista se basará en los alcances otorgados.

Tenga en cuenta que, por razones de compatibilidad, todos los ámbitos de OAuth 2.0 tendrán el prefijo "allow_", por ejemplo, el ámbito "read_prefs" se mostrará como permiso "allow_read_prefs".

=XML de respuesta

OBTENER /api/0.6/permisos

Devuelve el elemento de permisos único que contiene las etiquetas de permisos (tipo de contenido text/xml) 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generador="Servidor OpenStreetMap">
<permisos>
<nombre de permiso="permitir_preferencias_de_lectura"/>
		...
<nombre de permiso="permitir_leer_gpx"/>
<nombre de permiso="permitir_escribir_gpx"/>
</permisos>
</osm>

Respuesta JSON

OBTENER /api/0.6/permisos.json

Devuelve el elemento de permisos único que contiene las etiquetas de permisos (tipo de contenido application/json) 

{
 "versión": "0.6",
 "generador": "servidor OpenStreetMap",
 "permisos": ["permitir_lectura_preferencias", ..., "permitir_lectura_gpx", "permitir_escritura_gpx"]
}

Notas

Actualmente los siguientes permisos pueden aparecer en el resultado, correspondientes directamente a los utilizados en la definición de la aplicación OAuth 1.0a:

  • allow_read_prefs (leer preferencias del usuario)
  • allow_write_prefs (modificar las preferencias del usuario)
  • allow_write_diary (crear entradas de diario, comentarios y hacer amigos)
  • allow_write_api (modificar el mapa)
  • allow_write_redactions (redactar versiones de elementos)
  • allow_read_gpx (leer rastros GPS privados)
  • allow_write_gpx (cargar trazas GPS)
  • allow_write_notes (modificar notas)

Conjuntos de cambios

Para facilitar la identificación de los cambios relacionados, se introduce el concepto de conjuntos de cambios. Cada modificación de los elementos estándar de OSM tiene que hacer referencia a un conjunto de cambios abierto. Un conjunto de cambios puede contener etiquetas al igual que los demás elementos. Una etiqueta recomendada para los conjuntos de cambios es la clave comment=* con una breve descripción legible por humanos de los cambios que se están realizando en ese conjunto de cambios, similar a un mensaje de confirmación en un sistema de control de revisiones. Se puede abrir un nuevo conjunto de cambios en cualquier momento y se puede hacer referencia a un conjunto de cambios desde varias llamadas API. Debido a esto, se puede cerrar manualmente ya que el servidor no puede saber cuándo termina un conjunto de cambios y debe comenzar otro. Para evitar conjuntos de cambios abiertos obsoletos, se implementa un mecanismo para cerrar automáticamente los conjuntos de cambios en una de las siguientes tres condiciones:

  • 10 000 ediciones en un único conjunto de cambios (consulte el punto final de capacidades para conocer los límites específicos)
  • El conjunto de cambios ha estado abierto durante más de 24 horas.
  • No hubo cambios ni llamadas API relacionadas con un conjunto de cambios en 1 hora (es decir, tiempo de espera inactivo)

Tenga en cuenta que algunos conjuntos de cambios más antiguos pueden contener un poco más de 10 000 (o anteriormente 50 000) cambios debido a algunos fallos en la API.

Los conjuntos de cambios no son específicamente atómicos: los elementos agregados dentro de un conjunto de cambios serán visibles para otros usuarios antes de que se cierre el conjunto de cambios. Dada la cantidad de cambios que se pueden cargar en un solo paso, no es factible. En su lugar, se utiliza el bloqueo optimista como se describió anteriormente. Todo lo que se envíe al servidor en una sola solicitud se considerará de forma atómica. Para lograr la transaccionalidad para múltiples cambios, existe la nueva llamada API "diff upload".

Los conjuntos de cambios facilitan la implementación de reversiones. Al brindar información sobre los cambios realizados por una sola persona, resulta más fácil identificar los cambios realizados, en lugar de simplemente revertir una región completa. El soporte directo para la reversión no estará en la API, sino que será una forma de fusión inversa, donde el cliente puede descargar el conjunto de cambios, examinar los cambios y luego manipular la API para obtener los resultados deseados. Revertir un conjunto de cambios puede ser un proceso extremadamente complejo, especialmente si la reversión entra en conflicto con otros cambios realizados mientras tanto; esperamos que con el tiempo se creen aplicaciones expertas que permitan al usuario promedio revertir en varios niveles.

Para facilitar su uso, el servidor almacena un cuadro delimitador para cada conjunto de cambios y permite a los usuarios consultar los conjuntos de cambios en un área. El servidor calculará esto, ya que necesita buscar los nodos relevantes de todos modos. El cliente debe tener en cuenta que si las personas realizan muchos cambios pequeños en un área grande, se podrán encontrar coincidencias fácilmente. En este caso, los clientes deben examinar el conjunto de cambios directamente para ver si realmente se superponen.

Actualmente no es posible eliminar conjuntos de cambios, incluso si no contienen ningún cambio. El servidor puede eliminar posteriormente conjuntos de cambios que estén cerrados y que no contengan ningún cambio. Esto aún no está implementado.

Cálculo del cuadro delimitador

Así es como la API calcula el cuadro delimitador asociado con un conjunto de cambios:

  • Nodos: cualquier cambio en un nodo, incluida la eliminación, agrega la ubicación antigua y nueva del nodo al bbox.
  • Vías: Cualquier cambio en una vía, incluida la eliminación, agrega todos los nodos de la vía al bbox.
  • Relaciones:
    • agregar o quitar nodos o vías de una relación hace que se agreguen al cuadro delimitador del conjunto de cambios.
    • agregar una relación como miembro o cambiar los valores de las etiquetas hace que todos los nodos y miembros de la vía se agreguen al cuadro delimitador.
    • Esto es similar a cómo hace las cosas la llamada del mapa y es razonable bajo el supuesto de que agregar o eliminar miembros no cambia materialmente el resto de la relación.

Como optimización, el servidor creará un búfer ligeramente más grande que los objetos para evitar tener que actualizar el cuadro delimitador con demasiada frecuencia. Por lo tanto, un conjunto de cambios puede tener un cuadro delimitador diferente al de su reversión, y la distancia entre el cuadro delimitador y el siguiente nodo puede no ser constante para las cuatro direcciones.


Crear: PUT /api/0.6/changeset/create

La carga útil de una solicitud de creación de un conjunto de cambios son los metadatos de este conjunto de cambios. El cuerpo de la solicitud debe incluir uno o más elementos changeset, que opcionalmente incluyen una cantidad arbitraria de etiquetas (como 'comment', 'created_by", ...). Todos los elementos changeset deben estar incluidos en un elemento osm. 

<osm>
    <conjunto de cambios>
    <tag k="creado_por" v="JOSM 1.61"/>
    <tag k="comment" v="Solo agrego algunos nombres de calles"/>
	...
    </conjunto de cambios>
	...
</osm>

Si hay varios elementos changeset en el XML, se utilizan las etiquetas de todos ellos, y las posteriores anulan a las anteriores en caso de claves duplicadas.

Respuesta

El ID del conjunto de cambios recién creado con un tipo de contenido de text/plain

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando hay errores al analizar el XML
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP PUT

Notas

Se permite cualquier cantidad de etiquetas, posiblemente específicas del editor. Un editor podría, por ejemplo, incluir automáticamente información sobre qué imagen de fondo se utilizó, o incluso un poco de información de estado interno que facilitará la revisión del conjunto de cambios con el mismo editor más adelante, etc.

Los clientes deberían incluir una etiqueta created_by=*. Se recomienda a los clientes que se aseguren de que exista una etiqueta comment=*, que el usuario haya ingresado. Es opcional por el momento, pero esto podría cambiar en versiones posteriores de la API. Los clientes no deberían generar automáticamente la etiqueta de comentario, ya que esta etiqueta es para que el usuario final describa sus cambios. Los clientes pueden agregar cualquier otra etiqueta que consideren necesaria.

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

Devuelve el conjunto de cambios con el id dado en formato OSM-XML.

Parámetros

identificación
El id del conjunto de cambios a recuperar
incluir discusión
Indica si el resultado debe contener la discusión del conjunto de cambios o no. Si este parámetro tiene un valor, se devuelve la discusión. Si está vacío o se omite, la discusión no aparecerá en el resultado.

XML de respuesta

Devuelve el elemento de conjunto de cambios único que contiene las etiquetas de conjunto de cambios con un tipo de contenido de text/xml OBTENER /api/0.6/changeset/#id?include_discussion=true 

<osm version="0.6" generator="CGImap 0.9.3 (987909 spike-08.openstreetmap.org)" copyright="OpenStreetMap y colaboradores" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
<changeset id="10" creado_en="2008-11-08T19:07:39+01:00" abierto="verdadero" usuario="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" recuento_de_comentarios="3" recuento_de_cambios="10">
<tag k="creado_por" v="JOSM 1.61"/>
<tag k="comment" v="Solo agrego algunos nombres de calles"/>
		...
<discusión>
<comentario id="1234" fecha="2015-01-01T18:56:48Z" uid="1841" usuario="metaodi">
<text>¿Verificaste los nombres de esas calles?</text>
</comentario>
<comentario id="5678" fecha="2015-01-01T18:58:03Z" uid="123" usuario="fred">
<text>¡claro!</text>
</comentario>
			...
</discusión>
</conjunto de cambios>
</osm>

Respuesta JSON

Devuelve el elemento de conjunto de cambios único que contiene las etiquetas de conjunto de cambios con un tipo de contenido de application/json OBTENER /api/0.6/changeset/#id.json?include_discussion=true

Tenga en cuenta que el formato JSON cambió el 25 de agosto de 2024 con el lanzamiento de openstreetmap-cgimap 2.0.0, para alinearlo con el formato Rails existente. 

{
"versión": "0.6",
"generador": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
"copyright": "OpenStreetMap y colaboradores",
"atribución": "http://www.openstreetmap.org/copyright",
"licencia": "http://opendatacommons.org/licenses/odbl/1-0/",
"conjunto de cambios": {
"identificación": 10,
"creado_en": "2005-05-01T16:09:37Z",
"abierto": falso,
"comentarios_count": 1,
"número_de_cambios": 10,
"cerrado_a_las": "2005-05-01T17:16:44Z",
"min_años": 59.9513092,
"min_lon": 10.7719727,
"max_años": 59.9561501,
"longitud máxima": 10,7994537,
"uido": 24,
"usuario": "Petter Reinholdtsen",
"comentarios": [
      {
"identificación": 836447,
"visible": verdadero,
"fecha": "2022-03-22T20:58:30Z",
"uid": 15079200,
"usuario": "Ethan White de Cheriton",
"text": "wow nadie ha dicho nada aquí 22/3/2022\n"
      }
    ]
  }
}

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún conjunto de cambios con el ID indicado

Notas

  • ¿Es posible que el uid no esté disponible para los conjuntos de cambios generados automáticamente por la transición de API v0.5 a API v0.6?
  • Los atributos del cuadro delimitador faltarán en un conjunto de cambios vacío.
  • El cuadro delimitador del conjunto de cambios es un rectángulo que contiene los cuadros delimitadores de todos los objetos modificados en este conjunto de cambios. No es necesariamente el rectángulo más pequeño posible.
  • Esta llamada a la API solo devuelve información sobre el conjunto de cambios en sí, pero no sobre los cambios reales realizados a los elementos de este conjunto de cambios. Para acceder a esta información, utilice la llamada a la API "download".


Actualización: PUT /api/0.6/changeset/#id

Para actualizar etiquetas en el conjunto de cambios, por ejemplo, conjunto de cambios comment=foo.

La carga útil debe ser un documento OSM que contenga la nueva versión de un único conjunto de cambios. El cuadro delimitador, el tiempo de actualización y otros atributos se ignoran y no se pueden actualizar con este método. Solo las etiquetas proporcionadas en esta llamada permanecen en el objeto del conjunto de cambios. Para actualizar el cuadro delimitador, consulte el método expand_bbox. 

<ocho>
<conjunto de cambios>
<tag k="comment" v="Solo agrego algunos nombres de calles y un restaurante"/>
</conjunto de cambios>
</ocho>

Parámetros

identificación
El ID del conjunto de cambios que se va a actualizar. El usuario que realiza esta llamada a la API debe ser el mismo que creó el conjunto de cambios.

Respuesta

Un documento OSM que contiene la nueva versión del conjunto de cambios con un tipo de contenido de text/xml

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando hay errores al analizar el XML
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún conjunto de cambios con el ID indicado
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP PUT

Código de estado HTTP 409 (Conflicto) - text/plain

Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó

Notas

Las etiquetas que no se modifican deben repetirse para no eliminarse.


Cerrar: PUT /api/0.6/changeset/#id/close

Cierra un conjunto de cambios. Es posible que un conjunto de cambios ya se haya cerrado sin que el propietario haya realizado esta llamada a la API. En este caso, se devuelve un código de error.

Parámetros

identificación
El ID del conjunto de cambios que se cerrará. El usuario que realiza esta llamada a la API debe ser el mismo que creó el conjunto de cambios.

Respuesta

No se devuelve nada tras el cierre exitoso de un conjunto de cambios (código de estado HTTP 200)

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún conjunto de cambios con el ID indicado
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP PUT

Código de estado HTTP 409 (Conflicto) - text/plain

Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó

Descargar: GET /api/0.6/changeset/#id/download

Devuelve el documento OsmChange que describe todos los cambios asociados con el conjunto de cambios.

Parámetros

identificación
El id del conjunto de cambios para el que se solicita OsmChange.

Respuesta

El XML de OsmChange con un tipo de contenido de text/xml.

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún conjunto de cambios con el ID indicado

Notas

  • El resultado de llamar a esto puede cambiar mientras el conjunto de cambios esté abierto.
  • Los elementos en OsmChange están ordenados por marca de tiempo y número de versión.
  • Hay una llamada separada para obtener solo información sobre el conjunto de cambios en sí.


Expandir cuadro delimitador: POST /api/0.6/changeset/#id/expand_bbox (obsoleto, desaparecido)

Nota: este punto final se eliminó en diciembre de 2019. Consulte este problema de GitHub.


Consulta: GET /api/0.6/changesets

Este es un método API para obtener una lista de conjuntos de cambios. Admite el filtrado por distintos criterios.

Cuando se dan varias consultas, el resultado será el que cumpla con todos los requisitos. El contenido del documento devuelto son los conjuntos de cambios y sus etiquetas. Para obtener el conjunto completo de cambios asociados con un conjunto de cambios, utilice el método "download" en cada ID de conjunto de cambios individualmente.

Es posible que se requieran modificaciones y extensiones de las consultas básicas anteriores para soportar la reversión y otros usos que encontremos para los conjuntos de cambios.

Esta llamada devuelve conjuntos de cambios que coinciden con los criterios, ordenados por su fecha de creación. El orden predeterminado es el más nuevo primero, pero puede especificar order=oldest para invertir el orden de clasificación[3]. El orden inverso no se puede combinar con fecha.

Parámetros

bbox=min_lon,min_lat,max_lon,max_lat (O,S,E,N)
Buscar conjuntos de cambios dentro del cuadro delimitador dado
usuario=#uid o nombre_para_mostrar=#nombre
Buscar conjuntos de cambios por usuario con el ID de usuario o el nombre para mostrar indicados. Proporcionar ambos es un error.
tiempo=T1
Busca conjuntos de cambios "cerrados" después de T1. Compáralo con "from=T1", que filtra por fecha de creación.
tiempo=T1,T2
Buscar conjuntos de cambios que se "cerraron" después de T1 y que se "crearon" antes de T2. En otras palabras, cualquier conjunto de cambios que se abrió "en algún momento" durante el intervalo de tiempo dado de T1 a T2.
desde=T1 [&hasta=T2]
Busca conjuntos de cambios creados en T1 o después de T1 y (opcionalmente) antes de T2. to requiere from, pero no al revés. Si to se proporciona solo, no tiene efecto.
abierto=verdadero
Solo encuentra conjuntos de cambios que aún están "abiertos", pero excluye los conjuntos de cambios que están cerrados o que han alcanzado el límite de elementos para un conjunto de cambios (10.000 en este momento[4])
cerrado=verdadero
Solo encuentra conjuntos de cambios que están "cerrados" o que han alcanzado el límite de elementos
conjuntos de cambios=#cid{,#cid}
Busca conjuntos de cambios con los identificadores especificados (desde 2013-12-05)
order=[más nuevo|más antiguo]
Si es "más reciente" (predeterminado), ordena primero los conjuntos de cambios más nuevos. Si es "más antiguo", ordena en orden inverso.
límite=N
Especifica la cantidad máxima de conjuntos de cambios que se devuelven. Un número entre 1 y el valor límite máximo (actualmente 100). Si se omite, se utiliza el valor límite predeterminado (actualmente 100). Los valores límite máximo y predeterminado reales se pueden encontrar con una solicitud de capacidades.

Formato de hora: Cualquier cosa que la Time.parse función Ruby pueda analizar.

Respuesta

Devuelve una lista de todos los conjuntos de cambios ordenados por fecha de creación. El elemento <osm> puede estar vacío si no hubo resultados para la consulta. La respuesta se envía con un tipo de contenido de text/xml.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta) - text/plain

En el caso de parámetros mal formados, se devuelve un mensaje de texto que explica el error. En particular, si se intenta proporcionar tanto el UID como el nombre para mostrar como parámetros de consulta del usuario, se producirá este error.
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún usuario con el uid o display_name indicado.

Notas

  • Sólo se devuelven los conjuntos de cambios realizados por usuarios públicos.
  • Devuelve como máximo 100 conjuntos de cambios

Carga de diferencia: POST /api/0.6/changeset/#id/upload

Con esta llamada API, se pueden cargar archivos en formato OsmChange al servidor. Se garantiza que se ejecutará en una transacción. Por lo tanto, se aplican todos los cambios o ninguno.

Para cargar un archivo OSC, debe cumplir con la especificación OsmChange con las siguientes diferencias:

  • Cada elemento debe llevar un atributo "changeset" y un atributo "version", excepto cuando se crea un elemento en el que no se requiere la versión, ya que el servidor la establece por usted. El "changeset" debe ser el mismo que el ID del conjunto de cambios que se está cargando.
  • Un bloque <delete> en el documento OsmChange puede tener un atributo if-unused (cuyo valor se ignora). Si este atributo está presente, las operaciones de eliminación en este bloque son condicionales y solo se ejecutarán si el objeto que se va a eliminar no es utilizado por otro objeto. Sin el atributo if-unused, dicha situación generaría un error y toda la carga de diff fallaría. Configurar el atributo también hará que las eliminaciones de objetos ya eliminados no generen un error.
  • Los documentos OsmChange generalmente tienen atributos user y uid en cada elemento. Estos no son obligatorios en el documento cargado a la API.

Parámetros

identificación
El ID del conjunto de cambios al que pertenece esta diferencia.
datos POST
Los datos del archivo OsmChange

Respuesta

Si se aplica una diferencia correctamente, se devuelve un XML (tipo de contenido text/xml) en el siguiente formato 

<diffResult generador="Servidor OpenStreetMap" versión="0.6">
<nodo|vía|relación old_id="#" new_id="#" new_version="#"/>
	...
</diffResultado>

con un elemento por cada elemento en la carga. Tenga en cuenta que esto puede resultar contraintuitivo cuando el mismo elemento ha aparecido varias veces en la entrada y luego aparecerá varias veces en la salida.

¡¡Atributo!!crear
modificar eliminar
id_antiguo igual que el elemento cargado.
nuevo_id Nueva ID Nueva ID o igual a la cargada No presente
nueva_versión nueva versión no presente

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta) - text/plain

Cuando se producen errores al analizar el XML, se devuelve un mensaje de texto que explica el error.
Cuando falta un ID de marcador de posición o no es único (esto ocurrirá para referencias de relación circular)
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún conjunto de cambios con el ID indicado
O cuando la diferencia contiene elementos que no se pudieron encontrar para la identificación dada
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP POST

Código de estado HTTP 409 (Conflicto) - text/plain

Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
Si, durante la carga, se supera el tamaño máximo del conjunto de cambios, se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at.".
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó
O si la diferencia contiene elementos con ID de conjunto de cambios que no coinciden con el ID del conjunto de cambios al que se cargó la diferencia
O cualquiera de los mensajes de error que podrían ocurrir como resultado de una operación de creación, actualización o eliminación de uno de los elementos.
Código de estado HTTP 413 (Carga útil demasiado grande/Contenido demasiado grande)
Si durante la carga se excede el tamaño permitido del cuadro delimitador, se devuelve el error "Se excedió el límite de tamaño del cuadro delimitador del conjunto de cambios.".
Código de estado HTTP 429 (Demasiadas solicitudes)
Cuando la solicitud ha sido bloqueada debido a la limitación de velocidad
Otros códigos de estado
Cualquiera de los códigos de error y mensajes asociados que podrían ocurrir como resultado de una operación de creación, actualización o eliminación de uno de los elementos
Ver las secciones correspondientes en esta página

Notas

  • El procesamiento se detiene en el primer error, por lo que si hay varios conflictos en una carga diferente, solo se informa el primer problema.
  • Consulte /api/capabilities --> changesets -> maximum_elements para conocer la cantidad máxima de cambios permitidos en un conjunto de cambios.
  • Actualmente no hay límite en el tamaño de las diferencias en el puerto Rails. CGImap limita el tamaño de las diferencias a 50 MB (tamaño sin comprimir).
  • No se permite hacer referencias futuras a identificadores de marcadores de posición y la API los rechazará.

Resumen del conjunto de cambios

El procedimiento para la creación exitosa de un conjunto de cambios se resume en la siguiente imagen.

Tenga en cuenta que la imagen muestra operaciones de un solo objeto para crear, actualizar o eliminar elementos según la API 0.5. Por razones de rendimiento, se recomienda a los usuarios de la API que utilicen el punto de conexión de carga de diferencias de la API 0.6.

600px

Discusión sobre el conjunto de cambios

Las discusiones sobre conjuntos de cambios se agregaron en noviembre de 2014 (Ver blog)


Comentario: POST /api/0.6/changeset/#id/comment

Añade un comentario a un conjunto de cambios. El conjunto de cambios debe estar cerrado.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/comment (ejemplo)
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado.

Parámetros

texto
Texto del comentario. El tipo de contenido es "application/x-www-form-urlencoded".

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
si el campo de texto no estaba presente
Código de estado HTTP 409 (Conflicto)
El conjunto de cambios no está cerrado

Suscribirse: POST /api/0.6/changeset/#id/subscribe

Suscríbete a la discusión de un conjunto de cambios para recibir notificaciones de nuevos comentarios.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/subscribe ([ejemplo de https://api.openstreetmap.org/api/0.6/changeset/1000/subscribe])
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 409 (Conflicto)
si el usuario ya está suscrito a este conjunto de cambios


Cancelar suscripción: POST /api/0.6/changeset/#id/unsubscribe

Cancele la suscripción a la discusión de un conjunto de cambios para dejar de recibir notificaciones.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/unsubscribe (ejemplo)
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 404 (No encontrado)
si el usuario no está suscrito a este conjunto de cambios


Ocultar comentario del conjunto de cambios: POST /api/0.6/changeset/comment/#comment_id/hide

Establece la bandera visible en el comentario del conjunto de cambios como falso.

URL: https://api.openstreetmap.org/api/0.6/changeset/comment/#comment_id/hide
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado con rol de moderador.

Tenga en cuenta que el ID del comentario del conjunto de cambios difiere del ID del conjunto de cambios.

Códigos de error

Código de estado HTTP 403 (Prohibido)
si el usuario no es moderador
Código de estado HTTP 404 (No encontrado)
si el id del comentario del conjunto de cambios es desconocido


Mostrar comentario del conjunto de cambios: POST /api/0.6/changeset/comment/#comment_id/unhide

Establece el indicador visible en el comentario del conjunto de cambios como verdadero.

URL: https://api.openstreetmap.org/api/0.6/changeset/comment/#comment_id/unhide
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado con rol de moderador.

Tenga en cuenta que el ID del comentario del conjunto de cambios difiere del ID del conjunto de cambios.

Códigos de error

Código de estado HTTP 403 (Prohibido)
si el usuario no es moderador
Código de estado HTTP 404 (No encontrado)
si el id del comentario del conjunto de cambios es desconocido


Elementos

Existen llamadas de creación, lectura, actualización y eliminación para los tres elementos básicos de OpenStreetMap (Nodos, Vías y Relaciones). Estas llamadas son muy similares, excepto por la carga útil y algunos mensajes de error especiales, por lo que se documentan solo una vez.


Crear: PUT /api/0.6/[nodo|vía|relación]/crear

Crea un nuevo elemento del tipo especificado. Tenga en cuenta que toda la solicitud debe estar envuelta en un elemento <osm>...</osm>.

Un nodo: 

<ocho>
<nodo cambios conjunto="12" lat="..." lon="...">
<tag k="note" v="Solo un nodo"/>
		...
</nodo>
</osm>

Lejos: 

<osm>
<cambios de camino="12">
<tag k="nota" v="Sólo una forma"/>
		...
<nd ref="123"/>
<nd ref="4345"/>
		...
</camino>
</osm>

Una relación: 

<ocho>
<relación cambiosset="12">
<tag k="nota" v="Solo una relación"/>
		...
<tipo de miembro="nodo" rol="detener" ref="123"/>
<tipo de miembro="camino" ref="234"/>
</relación>
</osm>

Si se proporcionan varios elementos, solo se crea el primero. El resto se descarta (este comportamiento difiere de la creación de conjuntos de cambios).

Respuesta

El ID del elemento recién creado (el tipo de contenido es text/plain)

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta) - text/plain

Cuando se producen errores al analizar el XML, se devuelve un mensaje de texto que explica el error.
Cuando falta un ID de conjunto de cambios (desafortunadamente los mensajes de error no son consistentes)
Cuando un nodo está fuera del mundo
Cuando hay demasiados nodos para un camino
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP PUT

Código de estado HTTP 409 (Conflicto) - text/plain

Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó
Código de estado HTTP 412 (condición previa fallida)
Cuando una vía tiene nodos que no existen o no son visibles (es decir, eliminados): "La vía #{id} requiere los nodos con id en (#{missing_ids}), que no existen o no son visibles."
Cuando una relación tiene elementos que no existen o no son visibles: "La relación con id #{id} no se puede guardar debido a #{element} con id #{element.id}"
Código de estado HTTP 429 (Demasiadas solicitudes)
Cuando la solicitud ha sido bloqueada debido a la limitación de velocidad

Notas

  • Esto actualiza el cuadro delimitador del conjunto de cambios.
  • El atributo "rol" para las relaciones es opcional. El valor predeterminado es una cadena vacía.
  • Para evitar problemas de rendimiento al cargar varios objetos, se recomienda encarecidamente utilizar el punto final Diff upload.


Leer: GET /api/0.6/[nodo|vía|relación]/#id

Devuelve la representación XML del elemento.

XML de respuesta

GET /api/0.6/[nodo|vía|relación]/#id XML que representa el elemento, envuelto en un elemento <osm>: 

<osm>
<nodo id="123" lat="..." lon="..." versión="142" conjunto de cambios="12" usuario="fred" uid="123" visible="verdadero" marca de tiempo="2005-07-30T14:27:12+01:00">
<tag k="note" v="Solo un nodo"/>
		...
</nodo>
</osm>

Respuesta JSON

GET /api/0.6/[nodo|vía|relación]/#id.json JSON que representa el elemento, envuelto en un elemento <json>: 

{
"versión": "0.6",
"elementos": [
{"tipo": "nodo", "id": 4326396331, "lat": 31.9016302, "lon": -81.5990471, "marca de tiempo": "2016-07-31T00:08:11Z", "versión": 2, "conjunto de cambios": 41136027, "usuario": "maven149", "id": 136601}
 ]
}

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado
Código de estado HTTP 410 (desaparecido)
Si el elemento ha sido eliminado


Actualización: PUT /api/0.6/[node|way|relation]/#id

Actualiza los datos de un elemento preexistente. Se debe proporcionar una representación completa del elemento como debería ser después de la actualización. Las etiquetas, referencias de nodos de ruta y miembros de relación que permanezcan sin cambios también deben estar en la actualización. También se debe proporcionar un número de versión, que debe coincidir con la versión actual del elemento en la base de datos.

Este ejemplo es una actualización del nodo 4326396331, que actualiza la versión 1 para modificar las etiquetas existentes. Este cambio se realiza mientras el conjunto de cambios con id 188021 aún está abierto: 

<osm>
<nodo cambios conjunto="188021" id="4326396331" lat="50.4202102" lon="6.1211032" versión="1" visible="verdadero">
<etiqueta k="foo" v="barzzz" />
</nodo>
</osm>

Ejemplo para la vía 22935194 agregando una nueva clave zoning_code con valor B. Recuerde que al realizar el PUT a una vía existente, debe agregar todas las etiquetas existentes (aquí se excluyen algunas por brevedad) y la misma versión que la versión de OSM 

<osm>
<way id="22935194" conjunto de cambios="152700179" versión="9">
<tag k="autopista" v="residencial"/>
<tag k="código_de_zonificación" v="B"/>
<etiqueta k="nombre" v="Strada Desseanu"/>
</camino>
</osm>


= Respuesta

Devuelve el nuevo número de versión con un tipo de contenido de text/plain.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta) - text/plain

Cuando se producen errores al analizar el XML, se devuelve un mensaje de texto que explica el error (por ejemplo, se requiere la versión al realizar una actualización). Esto también puede ocurrir si se olvida pasar el encabezado Content-Length.
Cuando falta un ID de conjunto de cambios (desafortunadamente los mensajes de error no son consistentes)
Cuando un nodo está fuera del mundo
Cuando hay demasiados nodos para un camino
Código de estado HTTP 409 (Conflicto) - text/plain
Cuando la versión del elemento proporcionado no coincide con la versión actual de la base de datos del elemento
Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado
Código de estado HTTP 412 (condición previa fallida)
Cuando una vía tiene nodos que no existen o no son visibles (es decir, eliminados): "La vía #{id} requiere los nodos con id en (#{missing_ids}), que no existen o no son visibles."
Cuando una relación tiene elementos que no existen o no son visibles: "La relación con id #{id} no se puede guardar debido a #{element} con id #{element.id}"
Código de estado HTTP 429 (Demasiadas solicitudes)
Cuando la solicitud ha sido bloqueada debido a la limitación de velocidad

Notas

  • Esto actualiza el cuadro delimitador del conjunto de cambios.
  • Para evitar problemas de rendimiento al actualizar varios objetos, se recomienda encarecidamente el uso del punto de conexión Diff upload. Esta es también la única forma de garantizar que se actualicen varios objetos en una única transacción de base de datos.

Eliminar: ELIMINAR /api/0.6/[nodo|vía|relación]/#id

Espera una representación XML válida del elemento que se va a eliminar.

Por ejemplo: 

<osm>
<nodo id="..." versión="..." conjunto de cambios="..." lat="..." lon="..." />
</osm>

El ID del nodo en el XML debe coincidir con el ID en la URL, la versión debe coincidir con la versión del elemento que descargó y el conjunto de cambios debe coincidir con el ID de un conjunto de cambios abierto propiedad del usuario autenticado actual. Está permitido, pero no es necesario, tener etiquetas en el elemento, excepto las etiquetas de latitud y longitud, que son obligatorias; sin latitud y longitud, el servidor muestra un error 400 de solicitud incorrecta.

= Respuesta

Devuelve el nuevo número de versión con un tipo de contenido de text/plain.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta) - text/plain

Cuando se producen errores al analizar el XML, se devuelve un mensaje de texto que explica el error.
Cuando falta un ID de conjunto de cambios (desafortunadamente los mensajes de error no son consistentes)
Cuando un nodo está fuera del mundo
Cuando hay demasiados nodos para un camino
Cuando la versión del elemento proporcionado no coincide con la versión actual de la base de datos del elemento
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado

Código de estado HTTP 409 (Conflicto) - text/plain

Si el conjunto de cambios en cuestión ya se ha cerrado (ya sea por el propio usuario o como resultado de la función de cierre automático), se devuelve un mensaje con el formato "El conjunto de cambios #id se cerró a las #closed_at."
O si el usuario que intenta actualizar el conjunto de cambios no es el mismo que lo creó
Código de estado HTTP 410 (desaparecido)
Si el elemento ya ha sido eliminado
Código de estado HTTP 412 (condición previa fallida)
Cuando un nodo todavía es utilizado por una vía: El nodo n.° {id} todavía es utilizado por la vía n.° {way.id}.
Cuando un nodo todavía es miembro de una relación: El nodo #{id} todavía es utilizado por la relación #{relation.id}.
Cuando una vía todavía es miembro de una relación: La vía #{id} todavía la usa la relación #{relation.id}.
Cuando una relación sigue siendo miembro de otra relación: La relación #{id} se utiliza en la relación #{relation.id}.
Nota: cuando se devuelve como resultado de una operación de carga de OsmChange, los mensajes de error contienen una "s" plural falsa como en "... todavía usado por formas...", "... todavía usado por relaciones..." incluso cuando solo se devuelve 1 ID de forma o relación, ya que esto implica que se pueden devolver múltiples ID si el objeto eliminado era/es miembro de múltiples objetos principales, estas ID están separadas por comas.
Código de estado HTTP 429 (Demasiadas solicitudes)
Cuando la solicitud ha sido bloqueada debido a la limitación de velocidad

Notas

  • En versiones anteriores de la API no se requería ninguna carga útil. Ahora es necesaria debido a la necesidad de identificadores de conjuntos de cambios y números de versión.
  • Para evitar problemas de rendimiento al actualizar varios objetos, se recomienda encarecidamente el uso del punto de carga Diff. Esta es también la única forma de garantizar que se actualicen varios objetos en una sola transacción de base de datos.


Historial: GET /api/0.6/[nodo|vía|relación]/#id/history

Recupera todas las versiones antiguas de un elemento, ordenadas por número de versión desde la más antigua a la más nueva. (ejemplo)

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado

Versión: GET /api/0.6/[nodo|vía|relación]/#id/#versión

Recupera una versión específica del elemento.

Códigos de error

Código de estado HTTP 403 (Prohibido)
Cuando la versión del elemento no está disponible (debido a la redacción)
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado


Obtención múltiple: GET /api/0.6/[nodes|ways|relations]?#parameters

Permite a un usuario obtener múltiples elementos a la vez.

Parámetros

[nodos|vías|relaciones]=lista separada por comas
El parámetro debe ser el mismo en la URL (por ejemplo, /api/0.6/nodes?nodes=123,456,789)
Los números de versión para cada objeto se pueden proporcionar opcionalmente después del carácter "v" minúscula, p. ej. /api/0.6/nodes?nodes=421586779v1,421586779v2 (actualmente compatible solo con CGImap, se usa en osm.org [1] GitHub)

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
En caso de una solicitud mal formada (parámetros faltantes o incorrectos)
Código de estado HTTP 404 (No encontrado)
Si no se pudo encontrar uno de los elementos (por "no encontrado" se quiere decir que nunca existió en la base de datos, si el objeto fue eliminado, se devolverá con el atributo visible="false")
Código de estado HTTP 414 (URI de solicitud demasiado grande)
Si el URI era demasiado largo (se probó que tenía más de 8213 caracteres en el URI o más de 725 elementos para identificaciones de 10 dígitos cuando no se especificaban versiones)

Notas

Como la llamada de búsqueda múltiple devuelve objetos eliminados, es la forma práctica de determinar la versión en la que se eliminó un objeto (útil, por ejemplo, para la resolución de conflictos); la alternativa a usar esto sería la llamada de historial que, sin embargo, puede requerir potencialmente que se procesen miles de versiones.


Relaciones para el elemento: GET /api/0.6/[node|way|relation]/#id/relations

Devuelve un documento XML que contiene todas las relaciones (no eliminadas) en las que se utiliza el elemento dado.

Notas

  • No hay error si el elemento no existe.
  • Si el elemento no existe o no se utiliza en ninguna relación, se devuelve un documento XML vacío (aparte de los elementos <osm>)


Formas para el nodo: GET /api/0.6/node/#id/ways

Devuelve un documento XML que contiene todas las formas (no eliminadas) en que se utiliza el nodo dado.

Notas

  • No hay error si el nodo no existe.
  • Si el nodo no existe o no se utiliza de ninguna manera, se devuelve un documento XML vacío (aparte de los elementos <osm>)


Completo: GET /api/0.6/[way|relation]/#id/full

Esta llamada API recupera una vía o relación y todos los demás elementos a los que hace referencia.

  • Por camino, devolverá el camino especificado más el XML completo de todos los nodos referenciados por el camino.
  • Para una relación, devolverá lo siguiente:
    • La relación en sí
    • Todos los nodos, vías y relaciones que son miembros de la relación.
    • Más todos los nodos utilizados por las vías del paso anterior
    • La misma lógica recursiva no se aplica a las relaciones. Esto significa que si la relación r1 contiene la vía w1 y la relación r2, y w1 contiene los nodos n1 y n2, y r2 contiene el nodo n3, entonces una solicitud "completa" para r1 le dará r1, r2, w1, n1 y n2. No n3.

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ningún elemento con el id dado
Código de estado HTTP 410 (desaparecido)
Si el elemento ha sido eliminado


Redacción: POST /api/0.6/[nodo|vía|relación]/#id/#versión/redact?redaction=#redaction_id

Este es un método de API creado originalmente para el cambio de licencia de la ODbL para ocultar las contribuciones de los usuarios que no aceptaron la nueva licencia CT. Ahora lo utiliza el DWG para ocultar versiones antiguas de elementos que contienen infracciones de privacidad de datos o derechos de autor. Todas las solicitudes de recuperación de API para el elemento #version devolverán un error HTTP 403.

Notas

  • Solo se permite para cuentas OSM con rol de moderador (administradores de DWG y servidores)
  • requiere el alcance OAuth write_redactions; antes de septiembre de 2024 se requería write_api o write_redactions, y antes de diciembre de 2023 se requería write_api; esos requisitos de alcance más antiguos aún pueden estar disponibles en otros servidores basados ​​en sitios web de openstreetmap, como OpenHistoricalMap
  • El #redaction_id aparece en https://www.openstreetmap.org/redactions
  • Puede encontrar más información en el código fuente
  • Esta es una llamada extremadamente especializada.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
"No se puede redactar la versión actual del elemento, solo se pueden redactar versiones históricas".

Rastros GPS

En violación del [estándar GPX https://www.topografix.com/GPX/1/1/#type_trksegType] al descargar trazas GPX públicas a través de la API, todos los puntos de referencia de las trazas no rastreables se aleatorizan (o más bien se ordenan por latitud y longitud) y se entregan como un segmento de seguimiento por razones de privacidad. Las trazas rastreables se entregan, ordenadas por tiempo de carga descendente, antes que los puntos de referencia de las trazas no rastreables.


Obtener puntos GPS: Obtener /api/0.6/trackpoints?bbox=izquierda,abajo,derecha,arriba&page=número de página

Utilice esto para recuperar los puntos de seguimiento GPS que están dentro de un cuadro delimitador determinado (formateado en formato GPX).

dónde:

  • left es la longitud del lado izquierdo (más occidental) del cuadro delimitador.
  • bottom es la latitud del lado inferior (más al sur) del cuadro delimitador.
  • right es la longitud del lado derecho (más oriental) del cuadro delimitador.
  • top es la latitud del lado superior (más al norte) del cuadro delimitador.
  • pageNumber especifica qué grupo de 5000 puntos, o página, se debe devolver. Dado que el comando no devuelve más de 5000 puntos a la vez, este parámetro debe incrementarse y el comando debe enviarse nuevamente (utilizando el mismo cuadro delimitador) para recuperar todos los puntos de un cuadro delimitador que contenga más de 5000 puntos. Cuando este parámetro es 0 (cero), el comando devuelve los primeros 5000 puntos; cuando es 1, el comando devuelve los puntos 5001 a 10 000, etc.

El ancho máximo (derecha - izquierda) y la altura (arriba - abajo) del cuadro delimitador es de 0,25 grados.

Ejemplos

Recupere los primeros 5000 puntos para un cuadro delimitador: https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=0 Recupere los siguientes 5000 puntos (puntos 5001–10 000) para el mismo cuadro delimitador: https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=1

Respuesta

  • Esta respuesta NO está envuelta en un elemento padre xml de OSM.
  • El formato del archivo es GPX versión 1.0, que no es la versión actual. Verifique que sus herramientas lo admitan.
<?xml versión="1.0" codificación="UTF-8"?>
<gpx versión="1.0" creador="OpenStreetMap.org" xmlns="http://www.topografix.com/GPX/1/0">
<trk>
<nombre>20190626.gpx</nombre>
<desc>Senderos cerca del estanque Blackweir, Epping Forest</desc>
<url>https://api.openstreetmap.org/user/John%20Leeming/traces/3031013</url>
<trkseg>
<trkpt lat="51.6616100" lon="0.0534560">
<tiempo>2019-06-26T14:27:58Z</tiempo>
</trkpt>
			...
</trkseg>
		...
</trk>
	...
</gpx>


Crear: POST /api/0.6/gpx

También disponible en POST /api/0.6/gpx/create (obsoleto)

Utilice esta opción para cargar un archivo GPX o un archivo de archivos GPX. Requiere autenticación.

Los siguientes parámetros son necesarios en un mensaje HTTP multipart/form-data:

parámetro descripción
archivo El archivo GPX que contiene los puntos de la pista. Tenga en cuenta que para que el procesamiento sea correcto, el archivo debe contener puntos de la pista (<trkpt>), no solo puntos de referencia, y los puntos de la pista deben tener una marca de tiempo válida. Dado que el archivo se procesa de forma asincrónica, la llamada se completará correctamente incluso si el archivo no se puede procesar. El archivo también puede ser un archivo .tar, .tar.gz o .zip que contenga varios archivos gpx, aunque aparecerá como una sola entrada en el registro de carga.
descripción La descripción del rastro no puede estar vacía.
etiquetas Cadena que contiene etiquetas para el seguimiento. Puede estar vacía.
público 1 si el seguimiento es público, 0 si no lo es. Esto existe solo por compatibilidad con versiones anteriores; ahora se debe usar el parámetro de visibilidad en su lugar. Este valor se ignorará si también se proporciona visibilidad.
visibilidad Uno de los siguientes: privado, público, rastreable, identificable (para obtener explicaciones, consulte la página de carga de rastros de OSM o Visibilidad de los rastros de GPS)

Respuesta:

Un número que representa el ID del nuevo gpx

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando la descripción está vacía

Actualización: PUT /api/0.6/gpx/#id

Utilice esta opción para actualizar los metadatos de un archivo GPX. Solo puede utilizarlo la cuenta del propietario. Requiere autenticación. El cuerpo de la solicitud es un archivo xml con la misma estructura que las respuestas de Descargar metadatos.

El cuerpo de la respuesta estará vacío.

Eliminar: ELIMINAR /api/0.6/gpx/#id

Utilice esta opción para eliminar un archivo GPX. Solo puede utilizarlo la cuenta del propietario. Requiere autenticación.
El cuerpo de la respuesta estará vacío.


Descargar metadatos: GET /api/0.6/gpx/#id

También disponible en GET /api/0.6/gpx/#id/details (obsoleto)

Utilice esta opción para acceder a los metadatos de un archivo GPX. Disponible sin autenticación si el archivo está marcado como público. De lo contrario, solo lo puede usar la cuenta del propietario y requiere autenticación.

Ejemplo de respuesta "detalles": 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generador="Servidor OpenStreetMap">
<gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibilidad="pública" pendiente="falso" marca de tiempo="2010-10-09T09:24:19Z">
<description>Prueba de carga de PHP</description>
<etiqueta>prueba</etiqueta>
<etiqueta>php</etiqueta>
</archivo_gpx>
</osm>

Nota: el atributo uid se agregó en septiembre de 2023 GitHub.

Descargar datos: GET /api/0.6/gpx/#id/data

Utilice esta opción para descargar el archivo GPX completo. Disponible sin autenticación si el archivo está marcado como público. De lo contrario, solo lo puede usar la cuenta del propietario y requiere autenticación. ' La respuesta siempre será un archivo en formato GPX si utiliza un sufijo de URL .gpx, un archivo XML en un formato no documentado si utiliza un sufijo de URL .xml, de lo contrario la respuesta será el archivo exacto que se cargó.

NOTA: si su solicitud se refiere a un archivo de varios archivos, la respuesta cuando fuerce el formato gpx o xml consistirá en una concatenación simple no estándar de los archivos.


Lista: GET /api/0.6/user/gpx_files

Utilice esto para obtener una lista de seguimientos GPX propiedad del usuario autenticado: Requiere autenticación.

Tenga en cuenta que /user/ es una parte literal de la URL, no el nombre de usuario ni la identificación de usuario. (Esta llamada siempre devuelve rastros GPX del usuario autenticado actual solamente).

La respuesta es similar a la de Descargar metadatos, excepto que puede haber varios elementos <gpx_file>. Ejemplo: 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generador="Servidor OpenStreetMap">
<gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibilidad="pública" pendiente="falso" marca de tiempo="2010-10-09T09:24:19Z">
<description>Prueba de carga de PHP</description>
<etiqueta>prueba</etiqueta>
<etiqueta>php</etiqueta>
</archivo_gpx>
<gpx_file id="836620" name="track.gpx" lat="52.1194" lon="8.61807" uid="1234" user="Hartmut Holzgraefe" visibilidad="pública" pendiente="falso" marca de tiempo="2010-10-09T09:27:31Z">
<description>Prueba de carga de PHP 2</description>
<etiqueta>prueba</etiqueta>
<etiqueta>php</etiqueta>
</archivo_gpx>
</osm>

Métodos para datos de usuario

Detalles de un usuario: GET /api/0.6/user/#id

Este método API se agregó en septiembre de 2012 (código).

Puede obtener la ubicación de inicio y el nombre para mostrar del usuario mediante

XML de respuesta

OBTENER /api/0.6/usuario/#id Esto vuelve por ejemplo 

<osm version="0.6" generador="Servidor OpenStreetMap">
<id de usuario="12023" nombre_para_mostrar="jbpbis" cuenta_creada="2007-08-16T01:35:56Z">
<descripción></descripción>
<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>
<moderador/>
</roles>
<conjuntos de cambios cuentan="1"/>
<número de rastros="0"/>
<bloques>
<conteo recibido="0" activo="0"/>
<número de emisiones="68" activo="45"/>
</bloques>
</usuario>
</osm>

Respuesta JSON

OBTENER /api/0.6/usuario/#id.json 

{
"versión": "0.6",
"generador": "servidor OpenStreetMap",
"usuario": {"id": 12023, "nombre_para_mostrar": "jbpbis", "cuenta_creada": "2007-08-16T01:35:56Z", "descripción": "", "términos_del_colaborador": {"acordado": Falso}, "roles": [], "conjuntos_de_cambios": {"conteo": 1}, "rastros": {"conteo": 0}, "bloques": {"recibidos": {"conteo": 0, "activos": 0}}}
}

o un archivo vacío si no se encuentra ningún usuario para el identificador dado.

Tenga en cuenta que las cuentas de usuario que hayan realizado modificaciones pueden eliminarse. Dichos usuarios se enumeran en https://planet.osm.org/users_deleted/users_deleted.txt


Detalles de varios usuarios: GET /api/0.6/users?users=#id1,#id2,...,#idn

Este método API se agregó en julio de 2018 (código).

Puede obtener los detalles de varios usuarios a través de

XML de respuesta

OBTENER /api/0.6/users?users=#id1,#id2,...,#idn Esto vuelve por ejemplo 

<osm version="0.6" generador="Servidor OpenStreetMap">
<id de usuario="12023" nombre_para_mostrar="jbpbis" cuenta_creada="2007-08-16T01:35:56Z">
<descripción></descripción>
<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>
<conjuntos de cambios cuentan="1"/>
<número de rastros="0"/>
<bloques>
<conteo recibido="0" activo="0"/>
</bloques>
</usuario>
<id de usuario="210447" nombre_para_mostrar="siebh" cuenta_creada="2009-12-20T10:11:42Z">
<descripción></descripción>
<términos acordados por el colaborador="true"/>
<roles>
</roles>
<número de cambios="267"/>
<número de rastros="1"/>
<bloques>
<conteo recibido="0" activo="0"/>
</bloques>
</usuario>
</osm>

Respuesta JSON

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

{
"versión": "0.6",
"generador": "servidor OpenStreetMap",
"usuarios": [
{"usuario": {"id": 12023, "nombre_para_mostrar": "jbpbis", "cuenta_creada": "2007-08-16T01:35:56Z", "descripción": "", "términos_del_contribuidor": {"acordado": Falso}, "roles": [], "conjuntos_de_cambios": {"conteo": 1}, "rastros": {"conteo": 0}, "bloques": {"recibidos": {"conteo": 0, "activos": 0}}}},
{"usuario": {"id": 210447, "nombre_para_mostrar": "siebh", "cuenta_creada": "2009-12-20T10:11:42Z", "descripción": "", "términos_del_colaborador": {"acordado": Verdadero}, "roles": [], "conjuntos_de_cambios": {"conteo": 363}, "rastros": {"conteo": 1}, "bloques": {"recibido": {"conteo": 0, "activo": 0}}}}
 ]
}

o un archivo vacío si no se encuentra ningún usuario para el identificador dado.


Nota: Desde la solicitud de extracción 4203 (implementada el 26 de agosto de 2023), las variantes basadas en XML y JSON del punto final de usuarios omitirán cualquier usuario inexistente/suspendido/eliminado, en lugar de informar un error HTTP 404 no documentado previamente.

Detalles del usuario conectado: GET /api/0.6/user/details

Puede obtener la ubicación de inicio y el nombre para mostrar del usuario mediante

XML de respuesta

OBTENER /api/0.6/usuario/detalles Esto devuelve un documento XML del origen. 

<osm version="0.6" generador="Servidor OpenStreetMap">
<nombre_para_mostrar_usuario="Max Muster" cuenta_creada="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>
<número de cambios="4182"/>
<número de rastros="513"/>
<bloques>
<conteo recibido="0" activo="0"/>
</bloques>
<inicio lat="49.4733718952806" lon="8.89285988577866" zoom="3"/>
<description>La descripción de tu perfil</description>
<idiomas>
<lang>de-DE</lang>
<lang>el</lang>
<language>en-EE.UU.</lang>
<largo>y</long>
</idiomas>
<mensajes>
<número recibido="1" número no leído="0"/>
<número de envíos="0"/>
</mensajes>
</usuario>
</osm>

Respuesta JSON

OBTENER /api/0.6/usuario/detalles.json Esto devuelve un documento JSON del origen. 

{
"versión": "0.6",
"generador": "servidor OpenStreetMap",
"usuario": {
"identificación": 1234,
"display_name": "Requisitos máximos",
"cuenta_creada": "2006-07-21T19:28:26Z",
"description": "La descripción de tu perfil",
"contributor_terms": {"agreed": Verdadero, "pd": Verdadero},
"img": {"href": "https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"},
"roles": [],
"conjuntos de cambios": {"cuenta": 4182},
"rastros": {"cuenta": 513},
"bloques": {"recibidos": {"cuenta": 0, "activos": 0}},
"inicio": {"lat": 49.4733718952806, "lon": 8.89285988577866, "zoom": 3},
"languages": ["de-DE", "de", "en-US", "en"],
"mensajes": {"recibidos": {"cuenta": 1, "no leídos": 0},
"enviado": {"count": 0}}
 }
}

La sección de mensajes está disponible desde mediados de 2013. Proporciona un recuento básico de mensajes osm mensajes recibidos, enviados y no leídos.


Preferencias del usuario conectado: GET|PUT|DELETE /api/0.6/user/preferences

El servidor OSM permite almacenar preferencias de usuario arbitrarias. Los editores pueden utilizar esto, por ejemplo, para ofrecer la misma configuración dondequiera que el usuario inicie sesión, en lugar de una configuración almacenada localmente. Para obtener una descripción general de las aplicaciones que utilizan la API de preferencias y qué esquemas de claves utilizan, consulte esta página wiki.

Puede recuperar la lista de preferencias actuales utilizando

XML de respuesta

OBTENER /api/0.6/usuario/preferencias Esto devuelve un documento XML con el formato 

<osm version="0.6" generador="Servidor OpenStreetMap">
<preferencias>
<preferencia k="algunaclave" v="algunvalor" />
		...
</preferencias>
</osm>

Respuesta JSON

OBTENER /api/0.6/usuario/preferencias.json Esto devuelve un documento JSON con el formato 

{
"versión": "0.6",
"generador": "servidor OpenStreetMap",
"preferencias": {"algunaclave": "algúnvalor, ...}
}

PUT /api/0.6/usuario/preferencias

La misma estructura en el cuerpo del PUT cargará las preferencias. Todas las preferencias existentes se reemplazan por el conjunto recién cargado.

GET /api/0.6/user/preferences/[your_key] (sin los corchetes)

Devuelve una cadena con el valor de esa preferencia.

PUT /api/0.6/user/preferences/[your_key] (sin los corchetes)

Establecerá el valor de una única preferencia en una cadena pasada como contenido de la solicitud.

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

En este caso, la carga útil de la solicitud solo debe contener el valor de la preferencia, es decir, no debe tener formato XML.

La llamada PUT devuelve el código de respuesta HTTP 406 (no aceptable) si la misma clave aparece más de una vez, y el código 413 (entidad de solicitud demasiado grande) si intenta cargar más de 150 preferencias a la vez. Los tamaños de la clave y el valor están limitados a 255 caracteres.

Se puede eliminar una única entrada de preferencia con

ELIMINAR /api/0.6/user/preferences/[su_clave]


API de notas de mapas

Esto proporciona acceso a la función notas, que permite a los usuarios agregar notas textuales "post-it" georreferenciadas. Esta función no estaba originalmente en la API 0.6 y se agregó más tarde (23/04/2013 en la confirmación 0c8ad2f86edefed72052b402742cadedb0d674d9). Como se pensó como un reemplazo compatible para la API OpenStreetBugs, existen numerosas idiosincrasias en relación con el funcionamiento de otras partes de la API de OSM.


Recuperación de datos de notas mediante el cuadro delimitador: GET /api/0.6/notes

Devuelve las notas existentes en el cuadro delimitador especificado. Las notas se ordenarán por la fecha de su último cambio, siendo la más reciente la primera. La lista de notas se puede devolver en varios formatos diferentes (por ejemplo, como JavaScript ejecutable, XML, RSS, json y GPX) según la extensión del archivo.

Nota: el formato XML devuelto por la API es diferente del formato, igualmente no documentado, utilizado para los archivos de formato "osn", disponible en planet.openstreetmap.org, y como resultado de JOSM y Vespucci.

URL: https://api.openstreetmap.org/api/0.6/notes?bbox=izquierda,abajo,derecha,arriba (ejemplo)
Tipo de retorno: aplicación/xml

Parámetro Descripción Valores permitidos

¡Valor predeterminado!

bbox Coordenadas del área donde se recuperarán las notas Números de punto flotante en grados, que expresan un cuadro delimitador válido, no mayor que el límite de tamaño configurado, 25 grados cuadrados[a], sin superponerse con la línea de fecha. ninguno, parámetro requerido
límite Especifica el número máximo de entradas devueltas Un valor entre 1 y 10000[b] es válido 100[b]
cerrado Especifica el número de días que una nota debe estar cerrada para que ya no se devuelva Un valor de 0 significa que solo se devuelven las notas abiertas. Un valor de -1 significa que se devuelven todas las notas. 7
  1. ↑ consulte capacidades y esta línea en la configuración para el valor actual
  2. ↑ 2.0 2.1 puede cambiar, consulte capacidades para conocer el valor actual

Puede especificar el formato en el que desea que se devuelvan los resultados especificando una extensión de archivo. Por ejemplo, ejemplo para obtener los resultados en json. Actualmente, se admiten los formatos RSS, XML, json y gpx.

Las propiedades del comentario [uid, user, user_url] se omitirán si el comentario es anónimo.

XML de respuesta

OBTENER /api/0.6/notas 

<?xml versión="1.0" codificación="UTF-8"?>
<osm version="0.6" generator="Servidor OpenStreetMap" copyright="OpenStreetMap y colaboradores" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
<nota lon="0.1000000" lat="51.0000000">
<id>16659</id>
<url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659</url>
<url_comentario>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comentario</url_comentario>
<close_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close</close_url>
<fecha_de_creación>15 de junio de 2019 08:26:04 UTC</fecha_de_creación>
<status>abierto</status>
<comentarios>
<comentario>
<fecha>15 de junio de 2019 08:26:04 UTC</fecha>
<vid>1234</vid>
<user>nombreusuario</user>
<url_usuario>https://master.apis.dev.openstreetmap.org/user/nombre_usuario</url_usuario>
<action>abierto</action>
<text>EstoEsUnaNota</text>
<html>&lt;p&gt;EstoEsUnaNota&lt;/p&gt;</html>
</comentario>
			...
</comentarios>
</nota>
	...
</osm>

Respuesta JSON

OBTENER /api/0.6/notes.json 

{
"tipo": "Colección de características",
"características": [
  {
"tipo": "Característica",
"geometría": {"tipo": "Punto", "coordenadas": [0.1000000, 51.0000000]},
"propiedades": {
"identificación": 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",
"fecha_de_creación": "15/06/2019 08:26:04 UTC",
"estado": "abierto",
"comentarios": [
{"date": "2019-06-15 08:26:04 UTC", "uid": 1234, "user": "nombreDeUsuario", "user_url": "https://master.apis.dev.openstreetmap.org/user/nombreDeUsuario", "action": "opened", "text": "ThisIsANote", "html": "<p>ThisIsANote</p>"},
     ...
    ]
   }
  }
 ]
}

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando se cruza cualquiera de los límites

Leer: GET /api/0.6/notes/#id

Devuelve la nota existente con el ID indicado. El resultado puede estar en varios formatos (p. ej., XML, RSS, json o GPX) según la extensión del archivo.

URL: https://api.openstreetmap.org/api/0.6/notes/#id (xml, json)
Tipo de retorno: aplicación/xml

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ninguna nota con el ID indicado. Esto solo se debe devolver para notas que aún no existen.
Código de estado HTTP 410 (desaparecido)
Cuando un moderador ha ocultado la nota. Tenga en cuenta que el mensaje de error "La nota con el ID nnnnnnnnn ya ha sido eliminada" es engañoso, ya que en realidad no es posible que los usuarios que no son moderadores eliminen u oculten notas a través de la API.

Crear una nueva nota: POST /api/0.6/notes

XML

URL: https://api.openstreetmap.org/api/0.6/notes?lat=51.00&lon=0.1&text=EstaEsUnaNota (use Postman o herramientas similares para probar el punto final; tenga en cuenta que debe ser una solicitud POST)
Tipo de retorno: aplicación/xml

Se devolverá un archivo XML con los detalles de la nota.

JSON

URL: https://api.openstreetmap.org/api/0.6/notes.json
Contenido del cuerpo: {"lat":51.00, "lon": 0.1&, "text": "Esta es una nota\n\nEsta es otra línea"}
Tipo de retorno: aplicación/json

Se devolverá un archivo JSON con los detalles de la nota.

Parámetros

Parámetro Descripción Valores permitidos

¡Valor predeterminado!

<codigo>latitud</codigo> Especifica la latitud de la nota. número de punto flotante en grados No hay valor predeterminado, es necesario especificarlo
<código>lon</código> Especifica la longitud de la nota. número de punto flotante en grados No hay valor predeterminado, es necesario especificarlo
texto Un campo de texto con texto arbitrario que contiene la nota No hay valor predeterminado, debe estar presente

Si la solicitud se realiza como usuario autenticado, la nota se asocia a esa cuenta de usuario. Si el token de acceso OAuth utilizado no tiene el permiso allow_write_notes, se crea como una nota anónima.

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
si el campo de texto no estaba presente
Código de estado HTTP 404 (No encontrado)
Esto se aplica si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP POST


Crear un nuevo comentario: POST /api/0.6/notes/#id/comment

Añadir un nuevo comentario a la nota #id

URL: https://api.openstreetmap.org/api/0.6/notes/#id/comment?text=ThisIsANoteComment (use Postman o herramientas similares para probar el punto final; tenga en cuenta que debe ser una solicitud POST)
Tipo de retorno: aplicación/xml

Desde el 28 de agosto de 2019, esta solicitud debe realizarse como usuario autenticado.

La respuesta contendrá el XML de la nota.

Parámetro Descripción Valores permitidos

¡Valor predeterminado!

texto El comentario Un campo de texto con texto arbitrario Sin valor predeterminado, debe estar presente

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
si el campo de texto no estaba presente
Código de estado HTTP 404 (No encontrado)
si no hay ninguna nota con esa identificación disponible. Esto solo debería ocurrir con notas que aún no existen.
Esto también se aplica si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 409 (Conflicto)
Cuando la nota esta cerrada
Código de estado HTTP 410 (desaparecido)
Cuando un moderador ha ocultado la nota. Tenga en cuenta que el mensaje de error "La nota con el ID nnnnnnnnn ya ha sido eliminada" es engañoso, ya que en realidad no es posible que los usuarios que no son moderadores eliminen (oculten) notas a través de la API.

Cerrar: POST /api/0.6/notes/#id/close

Cerrar una nota como corregida.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/close?text=Comment (use Postman o herramientas similares para probar el punto final; tenga en cuenta que debe ser una solicitud POST)
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se encuentra ninguna nota con el ID indicado. Esto solo debería ocurrir con notas que aún no existen.
Esto también se aplica si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 409 (Conflicto)
Al cerrar una nota ya cerrada
Código de estado HTTP 410 (desaparecido)
Cuando un moderador ha ocultado la nota. Tenga en cuenta que el mensaje de error "La nota con el ID nnnnnnnnn ya ha sido eliminada" es engañoso, ya que en realidad no es posible que un no moderador elimine u oculte notas a través de la API.

Reabrir: POST /api/0.6/notes/#id/reopen

Reabrir una nota cerrada.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/reopen?text=Comentario (use Postman o herramientas similares para probar el punto final)
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ninguna nota con la identificación dada
Esto también se aplica si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 405 (Método no permitido)
Si la solicitud no es una solicitud HTTP POST
Código de estado HTTP 409 (Conflicto)
Al reabrir una nota ya abierta
Código de estado HTTP 410 (desaparecido)
Al volver a abrir una nota eliminada


Ocultar: ELIMINAR /api/0.6/notes/#id

Ocultar (eliminar) una nota.

URL: https://api.openstreetmap.org/api/0.6/notes/#id?text=Comentario (use Postman o herramientas similares para probar el punto final)
Tipo de retorno: aplicación/xml

Esta solicitud debe realizarse como usuario autenticado con rol de moderador.

Utilice la solicitud "Reabrir" para que la nota vuelva a ser visible.

Códigos de error

Código de estado HTTP 403 (Prohibido)
si el usuario no es moderador
Código de estado HTTP 404 (No encontrado)
Cuando no se pudo encontrar ninguna nota con la identificación dada
Código de estado HTTP 410 (desaparecido)
Al ocultar una nota que ya está oculta

Suscribirse: POST /api/0.6/notes/#id/subscription

Suscríbete a la discusión de una nota para recibir notificaciones de nuevos comentarios.

URL: https://api.openstreetmap.org/api/0.6/notes/:id/subscription
Tipo de retorno: (respuesta vacía)

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 404 (No encontrado)
si la nota no existe
Código de estado HTTP 409 (Conflicto)
si el usuario ya está suscrito a esta nota

Cancelar suscripción: ELIMINAR /api/0.6/notes/#id/subscription

Suscríbete a la discusión de una nota para recibir notificaciones de nuevos comentarios.

URL: https://api.openstreetmap.org/api/0.6/notes/:id/subscription
Tipo de retorno: (respuesta vacía)

Esta solicitud debe realizarse como usuario autenticado.

Códigos de error

Código de estado HTTP 404 (No encontrado)
si la nota no existe o el usuario no está suscrito a esta nota

Buscar notas: GET /api/0.6/notes/search

Devuelve las notas que coinciden con la consulta especificada. Si no se proporciona ninguna consulta, se devuelven las notas actualizadas más recientemente.

El resultado se puede codificar en varios formatos diferentes (XML, RSS, JSON o GPX), dependiendo de la extensión de archivo proporcionada.

URL: https://api.openstreetmap.org/api/0.6/notes/search </código>

Parámetro Descripción Valores permitidos

¡Valor predeterminado!

<código>q</código> Consulta de búsqueda de texto, que coincide con el texto de la nota o los comentarios. Cadena ninguno, parámetro opcional
límite Número máximo de resultados. Entero entre 1 y 10000[a] 100Template:Contenido
cerrado Número máximo de días que una nota ha estado cerrada. Número; El valor 0 devuelve solo notas abiertas, los números negativos devuelven todas las notas 7
nombre_para_mostrar Busque notas con las que interactuó el usuario determinado. Cadena; Nombre para mostrar del usuario ninguno, parámetro opcional
usuario Igual que display_name, pero la búsqueda se basa en el ID de usuario en lugar del nombre para mostrar. Cuando se proporcionan ambas opciones, display_name tiene prioridad. Entero; Id. de usuario ninguno, parámetro opcional
<código>bbox</código> Área de búsqueda. Cuadro delimitador; Área de 25 grados cuadrados como máximo[b] ninguno, parámetro opcional
<código>desde</código> Rango de fechas de inicio para created_at o updated_at (especificado por sort). Fecha; Preferiblemente en formato ISO 8601 ninguno, parámetro opcional
<código>a</código> Rango de fechas de finalización para created_at o updated_at (especificado por sort). Solo funciona cuando se proporciona from. Fecha; Preferiblemente en formato ISO 8601 ninguno, parámetro opcional
ordenar Ordenar resultados por fecha de creación o actualización. creado_en o actualizado_en actualizado_a
orden Orden de clasificación. más antiguo es orden ascendente, más nuevo es orden descendente. más antiguo o más nuevo más reciente

Template:Lista de notas

Ejemplos

Vea las últimas actualizaciones de notas a nivel mundial: https://api.openstreetmap.org/api/0.6/notes/search Buscar un texto en los comentarios: https://api.openstreetmap.org/api/0.6/notes/search?q=business%20spam Ver notas de un solo usuario: https://api.openstreetmap.org/api/0.6/notes/search?user=123 Busque notas más antiguas cerca de Null Island: https://api.openstreetmap.org/api/0.6/notes/search?bbox=-1%2C-1%2C1%2C1&sort=created_at&order=oldest&closed=-1&limit=20

Códigos de error

Código de estado HTTP 400 (solicitud incorrecta)
Cuando se cruza cualquiera de los límites

Fuente RSS: GET /api/0.6/notes/feed

Obtiene una fuente RSS para notas dentro de un área.

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

Tipo de retorno: aplicación/xml

Parámetro Descripción Valores permitidos

¡Valor predeterminado!

<código>bbox</código> Coordenadas del área donde se recuperarán las notas Números de punto flotante en grados, que expresan un cuadro delimitador válido, no mayor que el límite de tamaño configurado, 25 grados cuadrados [2], sin superponerse a la línea de fecha. ninguno, parámetro opcional

Cuando NO se debe utilizar la API

Para la carga masiva de scripts o la modificación de datos, el uso directo de la API puede no ser el mecanismo adecuado. La versión moderna de crear un script de carga masiva o modificación es crear un conjunto de cambios, cargarlo en un editor como JOSM y verificar el trabajo antes de confirmarlo. También puede utilizar la API para cargar un conjunto de cambios de manera atómica. Consulte también: Formatos de archivo de cambios, Importar

La API está destinada principalmente a la edición. Para proyectos o propósitos de solo lectura, consulte la Política de uso de la API.

Versión semántica

En el momento de la primera implementación, el control de versiones semántico (con un número de versión menor) no era un concepto establecido. Como resultado, la API no sigue este esquema. Muchas aplicaciones no podrían manejar correctamente los cambios de número de versión menor, por lo que no se intenta agregarlo, aunque se puede pensar que la versión actual es la 0.6.9.

Lectura adicional

Referencias

<referencias />

Categoría:API de OSM Categoría:Traducir al alemán Categoría:Traducir al español

  1. ↑ https://github.com/openstreetmap/openstreetmap-website/commit/b9c85c269726faad3c2613b37f01683c8b59f5c6#commitcomment-125789988
  2. ↑ https://github.com/openstreetmap/openstreetmap-website/commit/b9c85c269726faad3c2613b37f01683c8b59f5c6#commitcomment-125789640
  3. ↑ https://github.com/openstreetmap/openstreetmap-website/blob/f1c6a87aa137c11d0aff5a4b0e563ac2c2a8f82d/app/controllers/api/changesets_controller.rb#L174 - vea el estado actual en https://github.com/openstreetmap/openstreetmap-website/blob/master/app/controllers/api/changesets_controller.rb#L174
  4. ↑ https://api.openstreetmap.org/api/0.6/capabilities "<changesets maximum_elements="10000"/>"


Cite error: <ref> tags exist for a group named "lower-alpha", but no corresponding <references group="lower-alpha"/> tag was found

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=ES:API_v0.6&oldid=2796877"