FR:Overpass API/Overpass QL

From OpenStreetMap Wiki
Jump to: navigation, search
Langues disponibles — Overpass API/Overpass QL
· Afrikaans · Alemannisch · aragonés · asturianu · azərbaycanca · Bahasa Indonesia · Bahasa Melayu · Bân-lâm-gú · Basa Jawa · Baso Minangkabau · bosanski · brezhoneg · català · čeština · dansk · Deutsch · eesti · English · español · Esperanto · estremeñu · euskara · français · Frysk · Gaeilge · Gàidhlig · galego · Hausa · hrvatski · Igbo · interlingua · Interlingue · isiXhosa · isiZulu · íslenska · italiano · Kiswahili · Kreyòl ayisyen · kréyòl gwadloupéyen · Kurdî · latviešu · Lëtzebuergesch · lietuvių · magyar · Malagasy · Malti · Nederlands · Nedersaksies · norsk bokmål · norsk nynorsk · occitan · Oromoo · oʻzbekcha/ўзбекча · Plattdüütsch · polski · português · português do Brasil · română · shqip · slovenčina · slovenščina · Soomaaliga · suomi · svenska · Tiếng Việt · Türkçe · Vahcuengh · vèneto · Wolof · Yorùbá · Zazaki · српски / srpski · беларуская · български · қазақша · македонски · монгол · русский · тоҷикӣ · українська · Ελληνικά · Հայերեն · ქართული · नेपाली · मराठी · हिन्दी · অসমীয়া · বাংলা · ਪੰਜਾਬੀ · ગુજરાતી · ଓଡ଼ିଆ · தமிழ் · తెలుగు · ಕನ್ನಡ · മലയാളം · සිංහල · ไทย · မြန်မာဘာသာ · ລາວ · ភាសាខ្មែរ · ⵜⴰⵎⴰⵣⵉⵖⵜ · አማርኛ · 한국어 · 日本語 · 中文(简体)‎ · 吴语 · 粵語 · 中文(繁體)‎ · ייִדיש · עברית · اردو · العربية · پښتو · سنڌي · فارسی · ދިވެހިބަސް
Overpass turbo · API Overpass · Référence du langage · Exemples de requêtes · Guide du langage · Exemples avancés · Édition clairsemée · FAQ · MapCSS · plus : Overpass turbo français · Overpass API français

Cette traduction issue de la source anglaise v.2016-10-24 corrige quelques coquilles, mais peut en avoir créé d'autres : merci de rectifier si besoin.

Vue d'ensemble

Overpass QL est le deuxième langage de requête pour l'API Overpass et a été conçu comme une alternative à l'Overpass XML. Il a une syntaxe de style C : le code source de la requête se compose d'instructions, chacune finissant par un ";" (point-virgule). C'est une syntaxe impérative (par opposition à déclarative) : Les instructions sont exécutées l'une après l'autre, et leur état d'exécution s'accorde avec leur ordre sémantique.

L’exécution en cours s'applique au lot de données par défaut, ou à d'autres lots désignés, ou à la pile pour les déclarations de blocs. Un lot de données peut contenir des nodes, des ways, des relations et areas, ainsi que des types mixtes sans limitation en nombre. Les lots traités par les instructions créent des lots résultat, eux même lus en entrée par les instructions ultérieures. A défaut de spécifier un nom de lot comme entrée ou comme résultat, toutes les entrées sont implicitement lues par défaut et tous les résultats sont écrits vers la variable par défaut nommée "_" (un simple trait de soulignement). Les noms des lots peuvent être constitués de lettres, de chiffres et d'un trait de soulignement, mais ne doivent pas commencer par un chiffre. Une fois qu'un nouveau résultat est (implicitement ou explicitement) attribué à un lot existant, son contenu précédent est remplacé et n'est plus disponible. Les lots de données ont toujours une visibilité globale.

Il existe différents types d'instructions. Vous aurez presque toujours besoin de l'instruction print (out), qui est appelée une action, car cela fait sortir le résultat d'exécution (output). Les autres instructions sont regroupés en :

  • Requêtes autonomes : Ce sont des instructions complètes sur leur domaine.
  • Filtres : Ce sont toujours une partie des instructions d'une requête, elles contiennent les sélecteurs et les filtres souhaités.
  • Déclarations de blocs : Ces instructions traitent des regroupements et permettent des conditions ainsi que des boucles.
  • Préférences : Ce qui peut être défini en une fois au début, comme le format de sortie.

Lots de données

Overpass QL peut travailler avec des lots de données. Par défaut, tout est lu et envoyé au lot par défaut "_".

Pour envoyer quelque chose à un lot différent, utilisez la syntaxe "->". Exemple :

  (node[name="Foo"];)->.a;
stockera tous les nodes avec une clé name=Foo dans le jeu "a".

Pour sélectionner quelque chose dans un lot, complétez la commande avec ".a".

  node.a[amenity=foo];
retournera tous les nodes du lot "a" qui ont une clé amenity=foo.

Déclarations de blocs

Union

La déclaration d'un bloc union se fait sous forme d'une paire de parenthèses "( )". Dans un bloc union tout type d'instruction peut être utilisé, y compris des déclarations imbriquées de blocs union ou de boucles foreach.

  (declaration_1; declaration_2; )[->.lot_resultat];

On ne mentionne pas de lot d'entrée. Un lot résultat est généré par l'union des lots résultats de toutes les sous-déclarations, que leurs résultats soient redirigés ou non. Exemple :

  (node[name="Foo"];way[name="Foo"];);
La première déclaration collecte tous les nodes ayant une clé name="Foo", et la deuxième tous les ways ayant une clé name="Foo". Le lot résultat de la déclaration union contient les lots résultats des deux déclarations.

Le résultat d'une union peut être redirigé avec la syntaxe conventionnelle. Exemple :

  (node[name="Foo"];way[name="Foo"];)->.a;
C'est la même chose que l'exemple précédent mais avec le résultat écrit dans la variable "a".

Note : les instructions foreach et print ne peuvent pas être des sous-éléments d'une union.

Difference

La déclaration d'un bloc difference se fait sous forme d'une paire de parenthèses "( )". Dans un bloc difference on ne peut mettre que deux instructions séparées par un signe moins.

  (instruction_1; - instruction_2;)[->.lot_resultat];

On ne mentionne pas de lot d'entrée. La déclaration difference génère un lot résultat qui contient tous les éléments résultats de la première sous-déclaration mais ne figurant pas dans le résultat de la deuxième sous-déclaration. Exemple :

  (node[name="Foo"]; - node(50.0,7.0,51.0,8.0););
Cela collecte tous les nodes qui ont une clé nom="Foo", mais qui ne sont pas dans la zone délimitée.

Le lot résultat d'une déclaration difference peut être redirigé avec la syntaxe conventionnelle. Exemple :

  (node[name="Foo"]; - node(50.0,7.0,51.0,8.0);)->.a;
Cela est identique à l'exemple précédent, mais le résultat est écrit dans la variable "a".

Intersection

Il est également possible de produire un lot d'éléments qui apparaissent dans chacun des deux lots en entrée, c'est-à-dire qui font partie des deux lots. Le rappel est fait ici pour sa notion de comparaison entre des ensembles, similaire à la notion différence décrite ci-dessus, mais cela ne se fait pas par une déclaration de bloc. La méthode est décrite plus bas dans Par jeu d'entrée (.setname).

Boucle for-each (foreach)

La déclaration d'un bloc foreach se fait par le nom de l'instruction suivi d'une paire de parenthèses "foreach( )". Dans un bloc foreach tout type d'instruction peut être utilisé, y compris des déclarations imbriquées de blocs union ou de boucles foreach.

Il faut un lot d'entrée. Il n'y a pas génération d'un lot résultat. L'instruction foreach boucle sur le contenu du lot d'entrée, une fois pour chaque élément de ce lot. Exemple :

  way[name="Foo"];
  foreach(
    (
      ._;
      >;
    );
    out;
  );
Pour chaque way qui a une clé name="Foo", cela affiche les nodes de ce way immédiatement suivis par le way lui-même. Dans le détail, le lot résultat de way[name="Foo"] est pris comme lot d'entrée, et pour chaque élément de ce lot d'entrée le corps de la boucle est exécutée une fois. A l'intérieur de cette boucle l'union de l'élément way et de ses nodes est effectuée et écrite. Notez que lors de l'exécution, chaque sous-lot écrit durant l'itération est indépendant des sous-lots écrits lors d'autres itérations, ce qui peut générer des objets en double dans la sortie globale (aucune fusion n'est effectuée par l'instruction out au sein de la boucle).

Le lot d'entrée pour l'instruction foreach peut être extrait d'une variable avec la syntaxe conventionnelle. Exemple :

  foreach.a(...);
Cette boucle s'applique au contenu du lot "a" au lieu du lot par défaut "_".

Le nom de la variable à faire traiter par la boucle peut aussi être défini en ajoutant un nom de variable immédiatement avant la parenthèse d'ouverture. Exemple :

  foreach->.b(...);
Cela met l'élément à boucler dans la variable "b". Sans cela, l'instruction foreach ne déposerait pas les éléments dans un lot nommé.

Exemple, pour sélectionner l'entrée et changer le lot issu de la boucle :

  foreach.a->.b(...);
Note : l'entrée n'est pas corrompue par cette boucle. Toutes les mises à jour du lot sont sauvées pour un usage ultérieur, sans que cela n'altère le cycle d'itérations.

Requêtes autonomes

Item (.)

La requête autonome item (un simple point) se limite à la désignation d'un lot d'entrée.

Elle s'approprie l'identifiant du lot d'entrée spécifié. Ceci est particulièrement utile pour les déclarations union : elle reproduit son lot d'entrée comme (partie du) résultat de la déclaration union.

L'utilisation la plus courante est celle avec le lot d'entrée par défaut :

  ._;

Dans le contexte d'une déclaration union, ce qui suit retournera tous les éléments du lot d'entrée par défaut, combinés avec le résultat de recurse down.

  (._; >;);

Mais bien sur d'autres lots peuvent aussi être utilisés :

  .a;

Dans le contexte d'une déclaration union :

  (.a; .a >;);
Note : Les instructions ultérieures dans une déclaration union ne sont pas touchées par l'instruction item. En particulier ".a;" n'ajoutera pas le contenu du lot d'entrée au lot par défaut désigné "_".

L'instruction item peut aussi être utilisée comme filtre.

Recurse up (<)

La requête autonome recurse up s'écrit comme un simple "<" (inférieur à).

Il faut un lot d'entrée. Un lot résultat est généré. Ce lot résultat est composé de :

  • tous les ways qui ont un node apparaissant dans le lot d'entrée, plus
  • toutes les relations qui ont un node ou way apparaissant dans le lot d'entrée, plus
  • toutes les relations qui ont un way apparaissant dans le lot résultat.

Exemple :

  <;

Le lot d'entrée de l'instruction recurse up peut être choisi avec la syntaxe conventionnelle :

  .a <;

Le lot résultat de l'instruction recurse up peut être redirigé avec la syntaxe conventionnelle :

  < ->.b;

Bien sûr vous pouvez aussi les combiner ensemble :

  .a < ->.b;

Recurse up relations (<<)

La requête autonome recurse up relations a une syntaxe similaire à la requête recurse up et ne diffère que par deux aspects :

  • Elle s'écrit "<<" (double inférieur à).
  • Elle retourne récursivement toutes les relations qui ont une relation membre apparaissant dans le lot d'entrée.

En particulier on peut changer les lots d'entrée et/ou résultat avec la même syntaxe que décrite pour une requête autonome recurse up.

Précisément, la requête autonome recurse up relations retourne the transitive and reflexive closure of membership backwards.

Exemple :

  <<;

Recurse down (>)

La requête autonome recurse down s'écrit comme un simple ">" (supérieur à).

Il faut un lot d'entrée. Un lot résultat est généré. Ce lot résultat est composé de :

  • tous les nodes qui font partie d'un way apparaissant dans le lot d'entrée, plus
  • tous les nodes ou ways qui sont membres d'une relation apparaissant dans le lot d'entrée, plus
  • tous les nodes qui font partie d'un way apparaissant dans le lot résultat

En particulier on peut changer les lots d'entrée et/ou résultat avec la même syntaxe que décrite pour une requête autonome recurse up.

Exemple :

  >;

Recurse down relations (>>)

La requête autonome recurse down relations a une syntaxe similaire à la requête recurse down et ne diffère que par deux aspects :

  • Elle s'écrit ">>" (double supérieur à).
  • Elle retourne récursivement toutes les relations qui sont membre d'une relation apparaissant dans le lot en entrée.

En particulier on peut changer les lots en entrée et/ou résultat avec la même syntaxe que décrite pour une requête autonome recurse up.

Précisément, la requête autonome recurse down relations retourne the transitive and reflexive closure of membership.

Exemple :

  >>;

Requête pour des zones (is_in)

La requête autonome is_in renvoie les areas qui couvrent

  • les coordonnées données (lorsque spécifié) ou
  • les nodes du lot d'entrée (si aucune coordonnée n'est précisée).

Il faut, soit un lot d'entrée, soit les coordonnées ou éléments d'un lot résultat. Le résultat généré est l'ensemble des areas contenant les nodes du lot d'entrée ou des coordonnées spécifiées.

is_in ne peut pas cumuler directement tous les filtres Overpass QL. Pour filtrer un résultat is_in, une requête supplémentaire est nécessaire (voir ci-dessous) :

  [.lot_entree] is_in[->.lot_resultat];
  is_in(latitude,longitude)[->.lot_resultat];

Dans sa forme la plus réduite, le lot d'entrée par défaut est pris pour chercher les coordonnées. Exemple :

  is_in;

Le lot d’entrée peut être choisi à l'aide de la syntaxe conventionnelle :

  .a is_in;

Le lot résultat peut être redirigé à l'aide de la syntaxe conventionnelle :

  is_in->.b;

Bien sûr vous pouvez aussi les combiner ensemble :

  .a is_in->.b;

Au lieu de prendre des nodes existants, vous pouvez également spécifier des coordonnées avec deux nombres à virgule flottante, séparés par une virgule. Ils sont interprétés comme latitude et longitude. Dans ce cas le lot d'entrée est ignoré. Exemple :

  is_in(50.7,7.2);

Dans cette variante aussi, le résultat peut être redirigé à l'aide de la syntaxe conventionnelle :

  is_in(50.7,7.2)->.b;

Note : La création de la zone dépend de certaines règles d'extraction spécifiques, il n'y a pas d'équivalence de zone pour chaque objet OSM way ou relation ! Pour plus de détails, voir areas.osm3s et la page du wiki Overpass_API/Areas.

Pour filtrer le résultat renvoyé par is_in avec d'autres critères, une requête supplémentaire est nécessaire :

  is_in(48.856089,2.29789);
  area._[admin_level="2"];    // "._" représente le lot d'entrée par défaut, lequel contient toutes les zones retournées par "is_in"

Filtres

L'instruction la plus importante est l'instruction query. Ce n'est pas une instruction unique, car elle consiste plutôt au choix d'un des types d'objets node, way, relation (abréviation rel) ou area, suivi d'un ou plusieurs filtres. Le lot résultat est l'ensemble des éléments qui respectent les conditions de tous les filtres.

Exemple :

  node[name="Foo"];
  way[name="Foo"];
  rel[name="Foo"];
  area[name="Foo"];
node, way, rel and area sont les objets spécifiés, [name="Foo"] est le filtre défini, et ";" la fin de l'instruction.

Le résultat de l'instruction query peut être redirigé à l'aide de la syntaxe conventionnelle :

  node[name="Foo"]->.a;

Les filtres élémentaires peuvent s’additionner dans des lots d'entrée qui peuvent être modifiés par des filtres élémentaires. SVP, pour cela voir le filtre correspondant.

Par tag (has-kv)

Le filtre has-kv sélectionne tous les éléments qui ont ou n'ont pas une clé avec une certaine valeur. Il supporte les objets basiques d'OSM de type node, way, et relation ainsi que l'objet étendu area.

Il n'y a pas de lot d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de l'instruction, et non par ce filtre élémentaire.

Toutes ses conditions sont constituées d'un "[" (crochet d'ouverture) suivi d'une chaîne entre guillemets simples ou doubles, puis généralement d'un test spécifique, et se terminent par un "]" (crochet de fermeture). Si la chaîne alphanumérique ne se compose que de lettres, les guillemets peuvent être omis.

Les conditions "=" et "~" sur des clés et valeurs, avec ou sans expression régulière, peuvent être niées avec le caractère "!". Ainsi elles sélectionnent précisément les éléments qui ont un tag avec la clé donnée mais pas la valeur correspondante, ou les éléments qui n'ont pas de tag avec la clé donnée.

Égalité (=, !=)

Cette condition, la plus commune, sélectionne tous les éléments qui ont un tag contenant une clé à la valeur voulue. Cette condition contient une clé alphanumérique, suivi du signe "=" (égal) ou "!=" (différent de), et enfin une chaîne contenant la valeur cherchée. Exemples équivalents :

  node["name"="Foo"];         // trouve nodes avec clé "name", contenant la valeur exacte "Foo"
  node[name=Foo];
  node['name'="Foo"];
  node[name="Foo"];
  node["name"='Foo'];
  node["name"!='Foo'];        // trouve nodes avec clé "name", ne contenant pas la valeur exacte 'Foo'

Si vous avez un chiffre, une espace ou un caractère spécial dans la chaîne, vous devez utiliser des guillemets simples ou doubles :

  node["name"="Foo Street"];
  node["name"='Foo Street'];
  node[name="Foo Street"];

La recherche des valeurs vides n'est pas possible en utilisant l'opérateur "=". Cela ne peut se faire qu'en utilisant une expression régulière :

node[power=""];               // non supporté
node[power~"^$"];             // expression régulière à utiliser en substitution

De même, la recherche des clés de valeur vide dans les sous-clés n'est pas possible, et nécessite l'utilisation d'une expression régulière.

node[~"^$"~"."];              // trouver des nodes avec clé vide ("^$") ou toutes autres valeurs "."

NB: L'assistant Overpass Turbo dispose en conséquence d'une logique partielle de conversion automatique ""="".

Existence

Cette seconde condition sélectionne tous les éléments qui ont un tag avec une clé particulière de contenu quelconque. Il n'y a rien entre le "nom de clé" alphanumérique et le "]" :

  node["name"];
  node['name'];
  node[name];
Non existence

Cette variante sélectionne tous les éléments, qui n'ont pas un tag avec une clé particulière de contenu quelconque. Ce raccourci est disponible depuis la version 0.7.53.

  node[!"name"];
  node[!'name'];
  node[!name];

Dans les versions précédentes, not exists devait être écrit sous la forme node["name"!~".*"];.

Valeur correspondant à une expression régulière (~, !~)

Cette troisième condition sélectionne tous les éléments qui ont un tag avec une clé de valeur correspondant à une expression régulière. Elle contient la clé, et après le caractère "~" (tilde), une chaîne alphanumérique pour l'expression régulière à rechercher :

  node["name"~"^Foo"];        // trouve tout ce qui commence par "Foo"
  node["name"~"Foo$"];        // trouve tout ce qui se termine par "Foo"
  node["name"~"^Foo$"];       // trouve exactement "Foo"
  node["name"~"Foo"];         // trouve tout ce qui contient la sous-chaîne "Foo"
  node["name"~"."];           // trouve tous les nodes avec cette clé "name", quel que soit son contenu
  node["name"!~"."];          // trouve tous les nodes sans cette clé "name"

Notez que dans Overpass QL vous avez besoin d'échapper avec l'antislash. ["name"~"^St\."] retient l'expression régulière ^St. (qui trouve tous les noms commençant par "St"), alors que ["name"~"^St\\."] produit l'expression régulière plus probable ^St\. (qui trouve tous les noms commençant par "St."). Cela est dû aux règles d'échappement C et ne concerne pas la syntaxe XML.

Vous pouvez faire une recherche insensible à la casse, avec le paramètre ",i" :

  node["name"~"^Foo$",i];     // trouve "foo", "FOO", "fOo", "Foo" etc.

Clé/valeur correspondant à une expression régulière (~"key regex"~"value regex")

Cette quatrième condition sélectionne tous les éléments ou clé et valeur correspondent toutes deux à une expression régulière. Après le "~" (tilde) initial l'expression régulière pour la clé est produite, suivi d'un autre "~" et éventuellement une expression régulière pour la valeur.

  node[~"^addr:.*$"~"^Foo$"]; // trouve tags addr:* avec exactement "Foo"
  node[~"^addr:.*$"~"^Foo"];  // trouve tags addr:* avec tout ce qui commence par "Foo"
  node[~"^addr:.*$"~"Foo$"];  // trouve tags addr:* avec tout ce qui se termine par "Foo"
  node[~"^addr:.*$"~"Foo"];   // trouve tags addr:* avec tout ce qui contient la sous-chaîne "Foo"
  node[~"^addr:.*$"~"."];     // trouve tags addr:* quel que soit son contenu

Ce format prend également en charge les recherches insensibles à la casse

  node[~"^addr:.*$"~"^Foo$",i];  // trouve tags addr:* avec "foo", "FOO", "fOo", "Foo" etc.

Par boite de sélection (bbox)

Le filtre bbox sélectionne tous les éléments dans un certain cadre de sélection.

Il n'a pas de jeu d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi de quatre nombres à virgule flottante, séparés par des virgules, et se termine par une parenthèse fermante.

  (sud,ouest,nord,est)

Les nombres à virgule flottante donnent les limites de la boite de sélection : le premier est la limite sud ou la latitude minimum, le second est la limite ouest, habituellement la longitude minimum, le troisième est la limite nord ou la latitude maximale, le dernier est la limite est, habituellement la longitude maximale. Si le second argument est plus grand que le quatrième, la zone de délimitation traverse la longitude de 180 degrés. Exemple :

  node(50.6,7.0,50.8,7.3);

Recurse (n, w, r, bn, bw, br)

Le filtre recurse sélectionne en fonction du paramètre donné tous les éléments qui sont membres d'un élément du jeu d'entrée ou qui ont un élément du jeu d'entrée en tant que membre.

Le jeu d'entrée peut être modifié avec la syntaxe conventionnelle. Comme pour tous les filtres, le jeu résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi de l'un des symboles w (à l'amont de ways), r (à l'amont de relations), bn (à l'aval de nodes), bw (à l'aval de ways), ou br (à l'aval de relations), puis une déclaration optionnelle d'un jeu d'entrée, et se termine par une parenthèse fermante.

Exemples, avec le jeu d'entrée par défaut :

  node(w);        // sélectionne nodes enfants depuis tous les ways du jeu d'entrée
  node(r);        // sélectionne nodes membres de relations du jeu d'entrée
  way(bn);        // sélectionne ways parents pour tous les nodes depuis jeu d'entrée
  way(r);         // sélectionne ways membres des relations depuis jeu d'entrée
  rel(bn);        // sélectionne relations qui ont des nodes membres depuis jeu d'entrée
  rel(bw);        // sélectionne relations qui ont des membres ways depuis le jeu d'entrée
  rel(r);         // sélectionne tous les membres d'un type de relation depuis toutes les relations du jeu d'entrée
  rel(br);        // sélectionne toutes les relations parentes de toutes les relations depuis jeu d'entrée

Exemples, avec un jeu d'entrée modifié :

  node(w.foo);

Vous pouvez aussi limiter recurse à un rôle spécifique. Il suffit d'ajouter ":" (deux points) et le nom du rôle avant la parenthèse fermante.

Exemples, avec le jeu d'entrée par défaut :

  node(r:"rôle"); // sélectionne nodes membres de relations du jeu d'entrée
  way(r:"rôle");  // sélectionne ways membres des relations depuis le jeu d'entrée
  rel(bn:"rôle"); // sélectionne relations qui ont des nodes membres depuis jeu d'entrée
  rel(bw:"rôle"); // sélectionne relations qui ont des membres ways depuis le jeu d'entrée
  rel(r:"rôle");  // sélectionne tous les membres d'une relation type depuis toutes les relations du jeu d'entrée
  rel(br:"rôle"); // sélectionne toutes les relations parentes de toutes les relations depuis le jeu d'entrée

Exemples, avec un jeu d'entrée modifié :

  node(r.foo:"rôle");

Vous pouvez aussi chercher explicitement pour un rôle vide :

  node(r:"");
  node(r.foo:"");

Par jeu d'entrée (.setname)

Ce filtre se compose de l'instruction item (un simple point), suivi du nom du jeu d'entrée.

Comme pour tous les filtres, le jeu résultat est défini par l'ensemble de l'instruction, et non par ce filtre élémentaire.

Exemples, avec le jeu par défaut "_" :

  node._;

ou avec le jeu nommé "a".

  node.a;

Il est aussi possible de désigner plusieurs jeux d'entrée.

  node.a.b;

Cette instruction renvoie tous les nodes qui sont à la fois dans les jeux d'entrées "a" et "b" (intersection des jeux).

Par ID de l'élément (id-query)

Le filtre id-query sélectionne l'élément de type voulu avec l'ID donné. Il supporte les types de données OSM node, way, relation, et aussi area.

Il n'a pas de jeu d'entrée. Comme pour tous les filtres, le jeu résultat est défini par l'ensemble de l'instruction, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi d'un nombre entier positif, et se termine avec une parenthèse fermante.

Exemples :

  node(1);           // sélectionne node ayant id=1
  way(1);
  rel(1);
  area(1);

Notez que les IDs des areas doivent être dérivés d'un way OSM existant en ajoutant 2.400.000.000 à l'ID way ou respectivement pour une relation en ajoutant 3.600.000.000. Cela conduit à certaines contraintes d'extraction des areas, à savoir : tous les ways/relations ont une area en doublon. Voir areas.osm3s pour plus de détails.

Autour de (around)

Le filtre around sélectionne tous les éléments dans un certain rayon autour des éléments du jeu d'entrée. Si vous fournissez des coordonnées, celles-ci sont utilisées à la place du jeu d'entrée. Le jeu d'entrée peut être modifié avec la syntaxe conventionnelle. Comme pour tous les filtres, le jeu résultat est défini par l'ensemble de l'instruction, et non par ce filtre élémentaire.

Un rayon de "0" peut être utilisé pour un test d'intersection de ways sur leurs points internes et d'extrémité.

Ce filtre se compose d'une parenthèse ouvrante, suivi du mot-clé around, optionnellement d'une déclaration d'un jeu d'entrée, suivi après ":" (deux-points) d'un seul nombre à virgule flottante qui représente le rayon en mètres, et se termine par une parenthèse fermante ou est suivi par deux nombres à virgule flottante (indiquant latitude et longitude) séparés par une virgule, avant cette parenthèse fermante.

  (around[.input_set]:rayon)
  (around:rayon,latitude,longitude)

Exemples, avec le jeu d'entrée par défaut :

  node(around:100.0);
  way(around:100.0);
  rel(around:100.0);

Exemples, avec un jeu d'entrée modifié :

  node(around.a:100.0);

Exemples, avec des coordonnées :

  node(around:100.0,50.7,7.1);
  way(around:100.0,50.7,7.1);
  rel(around:100.0,50.7,7.1);

Exemple, pour trouver tous les cinémas de Bonn qui sont à moins de 100 mètres d'un arrêt de bus.

area[name="Bonn"];
node(area)[highway=bus_stop];
node(around:100)[amenity=cinema];
out;

Par polygone (poly)

Le filtre poly sélectionne tous les éléments du type choisi dans la zone de sélection donnée.

Il n'a pas de jeu d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi du mot poly, puis une chaîne contenant une quantité paire de nombres à virgule flottante, séparés seulement par des espaces (chaque paire de nombres représente une coordonnée, dans l'ordre latitude puis longitude), et se termine par une parenthèse fermante.

  (poly:"latitude_1 longitude_1 latitude_2 longitude_2 latitude_3 longitude_3 …");

Exemple, un triangle près de Bonn, Germany :

  node(poly:"50.7 7.1 50.7 7.2 50.75 7.15");
  way(poly:"50.7 7.1 50.7 7.2 50.75 7.15");
  rel(poly:"50.7 7.1 50.7 7.2 50.75 7.15");

Plus récent que (newer)

Le filtre newer sélectionne tous les éléments qui ont été modifiés depuis une date donnée. Par opposition à d'autres filtres, ce filtre ne peut pas être utilisé seul. Si la base de donnée interrogée gère l'historique des objets, alors le filtre changed est probablement un meilleur choix que newer.

Il n'a pas de jeu d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi d'une spécification de date (notez que cette spécification de date ne peut être abrégée et doit être mise entre guillemets simples ou doubles), et se termine par une parenthèse fermante.

Exemple :

  node._(newer:"2012-09-14T07:00:00Z");

Cette requête trouve tous les nodes qui ont changé depuis le 14 septembre 2012, 7 h UTC, dans le lot d'entrée donné.

Par date de changement (changed)

Le filtre changed sélectionne tous les éléments qui ont été modifiés entre deux dates données. Si une seule date est indiquée, la seconde est supposée être la date antérieure dans la base de données. Si une seule date est donnée et que l'éxécution se fait en temps réel, cela est exactement comme newer à deux exceptions près : d'une part c'est plus rapide, d'autre part il peut être appliqué comme filtre unique.

Il n'a pas de lot d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi d'une spécification de date (notez que cette spécification de date ne peut être abrégée et doit être mise entre guillemets simples ou doubles), ensuite peut suivre une virgule et la spécification d'une deuxième date, et se termine par une parenthèse fermante.

Exemple, tous les changements depuis la date donnée jusqu'a maintenant :

  node._(changed:"2012-09-14T07:00:00Z");

Exemple, tous les changements entre deux dates données :

  node._(changed:"2012-09-14T07:00:00Z","2012-09-14T07:01:00Z");

Par utilisateur (user, uid)

Le filtre user ou uid sélectionne tous les éléments qui ont été modifiés en dernier par l'utilisateur spécifié.

Il n'a pas de lot d'entrée. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi soit du mot-clé user puis ":" (deux-points) et une chaîne littérale indiquant le nom de l' utilisateur à rechercher, soit le mot-clé uid puis ":" suivi de l'ID de l'utilisateur à rechercher, et se termine par une parenthèse fermante.

Exemple :

  node(user:"Steve");
  node(uid:1);

Depuis la version 0.7.53, il est également possible de spécifier plusieurs noms d'utilisateurs :

   node(user:"Mapper1","Mapper2","Mapper...");
   node(uid:1,2,4,8,16);

Par zone (area)

Le filtre area sélectionne tous les éléments du type désigné qui sont à l'intérieur de la zone choisie (notez pour le cas des données d'archives que les zones sont toujours relatives aux données actuelles).

Le lot d'entrée peut être modifié avec la syntaxe conventionnelle. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivie du mot-clé area, ensuite éventuellement ":" (deux-points) et un entier non négatif, et se termine par une parenthèse fermante.

Les nodes sont retenus s'ils sont à l'intérieur ou sur la frontière de la zone. Les ways sont retenus si au moins un point (faisant partie d'un tronçon) est clairement à l'intérieur de la zone. Un way se terminant à la frontière et ne traversant pas la zone n'est pas retenu. Les relations sont retenues si l'un de leurs membres est clairement à l'intérieur de la zone.

Si l'instruction area est fournie sans nombre entier, les zones relatives au lot d'entrée sont utilisées :

  node(area);
  way(area);
  rel(area);

Même exemple, avec un jeu d'entrée modifié :

  node(area.a);
  way(area.a);
  rel(area.a);

Si un nombre entier est ajouté, le lot d'entrée est ignoré et l'area qui a ce nombre pour ID est retenue :

  node(area:2400000001);
  way(area:2400000001);
  rel(area:2400000001);

area(area); n'est actuellement pas pris en charge. Dans ce cas, le filtre area sera ignoré silencieusement, conduisant à des résultats inattendus.

Les areas ne sont pas des éléments natifs d'OSM, mais sont déduites de la base de données OSM en utilisant les ways fermés ou les relations ; cette méthode permet de regrouper leurs différentes représentations dans un ensemble cohérent qui peut stocker leur géométrie indépendamment de leur complexité et de leur représentation dans la base de données d'OSM, comme si elles étaient un seul élément distinctif, sans utiliser des règles de filtrage complexes dans votre requête. Cependant l'association de ces objets avec un attribut "ID OSM" nécessite une adaptation car le même identifiant peut être utilisé pour des éléments sans rapport d'un type différent (way ou relation). Pour cette raison, les zones retournées par l'API Overpass ont seulement un "ID virtuel" spécifique à l'API Overpass, mais ne figurent pas directement dans la base de données d'OSM.

Par convention, l'ID area peut être calculé à partir d'un way OSM existant en ajoutant 2.400.000.000 à son "ID OSM", ou respectivement dans le cas d'une relation en ajoutant 3.600.000.000. Notez que la création de cette zone est soumise à certaines règles d'extraction, à savoir tous les ways/relations n'ont pas forcement une area associée (notamment ceux qui sont tagués avec area=no, et la plupart des multipolygones qui n'ont pas de name=* défini et ne correspondent pas à une zone).

Les zones sont créées par un job différé sur le serveur API Overpass et ont généralement un décalage de plusieurs heures par rapport à la base de données instantanée OSM. L'horodatage exact peut être déterminé en vérifiant la valeur `timestamp_areas_base` dans le résultat Overpass json ou xml.

Si vous souhaitez des résultats immédiats (ne dépendant pas d'un traitement par lots différé), vous pouvez écrire vos propres filtres sans utiliser cette methode dans votre requête : utilisez les IDs des éléments standard d'OSM et filtrez les par des tags adaptés à votre choix.

Voir areas.osm3s pour des précisions sur les filtres (écrits en utilisant la variante XML du langage de requête Overpass) actuellement utilisés par Overpass pour générer les zones interrogeables par cette méthode. Ces zones sont définies en utilisant la fonction de requête pivot (voir ci-dessous).

Élément englobant (pivot)

Le filtre pivot sélectionne l'élément du type choisi qui définit le contour de la zone donnée.

Le lot d'entrée peut être modifié avec la syntaxe conventionnelle. Comme pour tous les filtres, le lot résultat est défini par l'ensemble de la déclaration, et non par ce filtre élémentaire.

Ce filtre se compose d'une parenthèse ouvrante, suivi du mot pivot, et se termine par une parenthèse fermante.

L'instruction retient pour chaque zone dans le lot d'entrée l'élément respectif qui a été généré depuis cette zone. Ce qui est soit une relation multipolygone soit un way.

Exemples :

  way(pivot);
  rel(pivot);

Mêmes exemples, avec un jeu d'entrée modifié :

  way(pivot.a);
  rel(pivot.a);

L'exemple suivant détermine d'abord la zone pour le "comté de Greater London first" et la stocke dans un lot resultat nommé ".londonarea". Dans la ligne suivante les zones contenues dans le lot ".londonarea" sont reconverties dans leurs relations correspondantes OSM en utilisant le filtre pivot. Finalement l'instruction out geom; extrait les relations (en incluant ways et nodes).

area[name="London"][admin_level=6][boundary=administrative]->.londonarea;
rel(pivot.londonarea);
out geom;

Actions

Il n'existe actuellement qu'une seule action. Cette action imprime (fait sortir) le contenu désigné comme lot d'entrée.

Print (out)

L'action out peut être configurée en ajoutant un nombre variable de paramètres séparés par des espaces, entre le mot out et le point-virgule.

L'action out s'éxécute sur un lot d'entrée. Elle ne retourne pas de lot résultat. Le lot d'entrée peut être changé par le nom de variable voulu en début d'instruction.

Les paramètres autorisés, dans un ordre quelconque, sont :

  • le niveau de verbosité parmi les suivants, body par défaut :
    • ids : Imprime seulement les IDs des éléments.
    • skel : Imprime aussi les informations nécessaires pour la géométrie. Ce sont entre autres les coordonnées des nodes, des ways, et les IDs des membres de relations pour les ways et les relations.
    • body : Imprime toutes les informations nécessaires pour utiliser les données. Ce sont, entre autres, les tags de tous les éléments et les rôles des membres de relation.
    • Tags : Imprime seulement les IDs et tags de chaque élément sans les coordonnées des membres.
    • meta : Imprime toutes les informations associées aux éléments. Cela complète la sortie body, de la version, de l'id du changeset, de l'horodatage et des données du dernier utilisateur qui a touché chaque élément.
  • Un des arguments suivants pour des informations dérivées :
    • bb : Ajoute la boite de sélection de chaque élément à ces éléments. Pour les nodes ceci est équivalent à geom. Pour les ways c'est la boite de sélection englobant tous leurs nodes. Pour les relations, c'est la boîte de selection englobant tous les nodes et ways membres, sans que cela s'applique aux relations membres.
    • center : Ajoute le centre de la boite de sélection mentionnée ci-dessus aux ways' et relations. Note : Il n'est pas garanti que le point central se trouve à l'intérieur du polygone (exemple).
    • geom : Ajoute la géométrie complète à chaque objet. Cela ajoute les coordonnées à chaque node, ainsi qu'à chaque node membre d'un way ou d'une relation, et ajoute une liste de membres "nd" avec leurs coordonnées à toutes les relations.
L'attribut "geom" peut être suivi d'une boite de sélection au format "(sud, ouest, nord, est)". Dans ce cas, seules les coordonnées des éléments à l'intérieur de cette boite de sélection sont restituées. Pour les segments de ways la première coordonnée hors de la boite de sélection est fournie pour permettre de créer proprement ces segments.
  • Un des éléments suivants pour l'ordre de tri peut être ajouté, asc par défaut :
    • asc : Trie par ID objet.
    • qt : Trie par index quantile ; ce qui est à peu près géographique et nettement plus rapide que le classement par ids.
  • Un nombre entier positif pour le nombre maximum d'éléments à imprimer, sans limite par défaut.

Exemple, imprimer les éléments sans métadonnées :

  out;

Exemple, imprimer les éléments avec métadonnées :

  out meta;

Exemple, imprimer jusqu'à 99 éléments :

  out 99;

Exemple, imprimer jusqu'à 1.000.000 éléments, classés par lieux, avec métadonnées :

  out meta qt 1000000;

Exemple, lire à partir de la variable "a" les données à sortir.

  .a out;

Préférences

Durée max (timeout)

La préférence timeout a pour argument un entier non négatif. Sa valeur par défaut est "180".

Ce paramètre indique la durée maximale en secondes d'exécution de la requête, choisie par l'utilisateur. Si la requête veut s'exécuter plus longtemps que cette durée, le serveur peut l'annuler par timeout. Le choix d'une valeur trop élevée est une seconde cause de rejet de la requête par le serveur sans l'exécuter.

Si vous envoyez une grande requête très complexe, choisissez une valeur supérieure, par exemple "3600" pour une heure, mais assurez-vous que votre fournisseur soit assez tolérant pour ne pas l'interrompre en raison de la durée elle-même.

Exemple :

  [timeout:180]

Taille max (maxsize)

La préférence maxsize a pour argument un entier non négatif. Sa valeur par défaut est "536870912" (512 Mo).

Ce paramètre indique la mémoire maximale autorisée pour la requête, en octets de RAM sur le serveur, comme souhaité par l'utilisateur. Si la requête a besoin de plus de RAM que cette valeur, le serveur peut l'interrompre par dépassement mémoire. Le choix d'une valeur trop élevée est une seconde cause de rejet de la requête par le serveur sans l'exécuter.

Si vous envoyez une grande requête très complexe, choisissez une valeur supérieure, par exemple "1073741824" (1 Go). Comme la valeur maximale dépend fortement de la charge instantanée du serveur, les demandes de 2 Go par exemple seront probablement rejetées pendant les heures de pointe, car elles ne rentrent pas dans la gestion globale des ressources. Techniquement parlant, maxsize est traité comme un nombre de 64 bits signé.

Exemple :

  [maxsize:1073741824]

Important : Récemment un nouveau mécanisme a été introduit pour annuler les requêtes supérieures à 2 Go de mémoire. La taille exacte de cette limite est encore en discussion et pourrait changer au fil du temps. Si vous rencontrez des messages d'erreur comme "runtime error: Query run out of memory using about 2048 MB of RAM.", il serait utile de lire ce message

Format de sortie (out)

Remarque : ne pas confondre la préférence out et l'action out. Leurs syntaxes ne doivent pas être mélangées.

La préférence out définit le format de sortie des données OSM. Elle peut prendre l'une de ces cinq valeurs :

  • xml
  • json (ne pas confondre avec geoJSON)
  • csv
  • custom
  • popup

La valeur par défaut est xml.

Exemple :

[out:json]
Personnalisation du format CSV

Le choix csv renvoi le résultat comme un document csv qui peut être directement ouvert avec un outil tel que LibreOffice. Il requiert des paramètres de configuration supplémentaires pour définir la liste des champs à afficher, et dispose de deux paramètres optionnels : pour la ligne d'en-tête et pour le séparateur à utiliser.

[out:csv( fieldname_1 [,fieldname_n ...] [; csv-headerline [; csv-separator-character]] )]
Liste des noms de champs

En plus des noms de champs OSM normaux les champs spéciaux suivants sont disponibles :

Noms de champs spéciaux Description
 ::id ID objet OSM
 ::type Type objet OSM : node, way, relation
 ::otype Valeur numerique de l'objet OSM
 ::lat Latitude (disponible pour nodes, ou avec l'action out center)
 ::lon Longitude (disponible pour nodes, ou avec l'action out center)
Les champs d'information meta suivants sont disponibles seulement si l'action out méta; est utilisé pour la sortie.
 ::version Numéro de version des objets OSM
 ::timestamp Dernier horodatage de l'objet OSM
 ::changeset Changeset dans lequel l'objet a été modifié
 ::uid ID user OSM
 ::user Nom user OSM

Notez que tous ces noms de champs spéciaux doivent être préfixés par deux fois "deux-points".

Exemple :

[out:csv(::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck)];

Exemple, stations de chemin de fer à Bonn :

[out:csv(::id,::type,"name")];
area[name="Bonn"]->.a;
( node(area.a)[railway=station];
  way(area.a)[railway=station];
  rel(area.a)[railway=station]; );
out;
Ligne d'en-tête

La ligne d'en-tête est le premier paramètre optionnel qui peut être ajoutée juste après la liste des champs et un séparateur point-virgule. Les valeurs possibles sont true et false. Si ce paramètre n'est pas spécifié, une ligne d'en-tête sera imprimé.

[out:csv(::"id",amenity,name,operator,opening_hours,"contact:website","contact:phone",brand, dispensing, lastcheck;false)];
Caractère séparateur de champs

Par défaut, tous les champs sont séparés par un caractère de tabulation (\t). Cependant, ce choix peut être modifié via le second paramètre optionnel. Dans l'exemple suivant tous les champs de sortie seront séparés par un caractère "|" (barre verticale).

[out:csv(::"id",amenity,name,operator,opening_hours,"contact:website","contact:phone",brand, dispensing, lastcheck;true;"|")];
Vérification de la complétion des données

Contrairement à d'autres modes de sortie comme XML et JSON, il n'y a actuellement pas de message d'erreur pour tout. Un résultat vide (ou juste avec une ligne d'en-tête) peut indiquer, soit que rien n'a été trouvé, ou que la requête a été annulée par un temps limite ou une autre erreur plus sérieuse. Une façon de contourner cela est d'introduire un compteur supplémentaire, qui résume le résultat de la requête précédente et est toujours mis comme dernière déclaration de sortie d'une requête.

L'exemple ci-dessous complète celui sur les stations de chemin de fer à Bonn par l'ajout d'un comptage à la sortie :

[out:csv(::type,::id,"name",::count)];
area[name="Bonn"]->.a;
( node(area.a)[railway=station];
  way(area.a)[railway=station];
  rel(area.a)[railway=station]; );
out;
out count;

Notez que le résultat inclut désormais une ligne supplémentaire count dans colonne @type et une indication sur le nombre total d'éléments contenus dans le lot de resultat actuel. Si la ligne finale de décompte est manquante ou que le nombre total differe, vous saurez avec certitude que quelque chose s'est mal déroulé, et que les résultats de la requête sont incomplets/incoherents.

@type  @id         name               @count
node   26945519    Bonn-Oberkassel    
node   1271017705  Bonn-Beuel         
node   2428355974  Bonn-Bad Godesberg 
node   2713060210  Bonn Hauptbahnhof  
node   3400717493  Bonn-Mehlem        
count                                 5
Formats custom et popup

Les formats de sortie custom et popup sont également configurables ; merci de voir les détails sur cette page (en anglais) output formats documentation.

Boîte de sélection globale (bbox)

La préférence bbox définit le cadre de sélection à l'intérieur duquel sera implicitement effectué toutes les recherches (à moins de spécifier explicitement une autre bbox).

La boîte de sélection est décrite par les coordonnées de ses quatre côtés dans cet ordre : latitude sud, longitude ouest, latitude nord, longitude est (qui le standard de la norme ISO 6709).

  [bbox:sud,ouest,nord,est]

Exemple :

  [bbox:50.6,7.0,50.8,7.3]
Impose un cadre de recherche correspondant à peu près à la ville allemande de Bonn (coordonnées : +50.7N +7.15E).

Si la requête est une URL avec un paramètre data=, les coordonnées de la boîte peuvent être rajoutées comme paramètre supplémentaire. L'ordre des coordonnées est alors longitude-latitude ; cet ordre est celui utilisé par OpenLayers et d'autres frameworks.

Exemple :

  /api/interpreter?data=[bbox];node[amenity=post_box];out;&bbox=7.0,50.6,7.3,50.8
Cette requête trouve toutes les boîtes aux lettres de la zone de Bonn, en Allemagne.

Données archivées (date)

La préférence date indique à la base de données qu'elle doit répondre à une requête basée sur son état à une date passée. Ceci est utile, par exemple, pour reconstruire des données vandalisées.

On utilise l'identifiant "date", suivi de "deux-points" puis de la spécification d'une date.

Exemple:

  [date:"2012-09-12T06:55:00Z"]
La requête sera exécutée comme si elle avait été lancée le 12 septembre 2012 à 6h55 UTC.

Limitation : La plus ancienne date utilisable est le 12 septembre 2012 à 6h55 UTC (1347432900 en secondes-système). Ceci correspond à la première modification effectuée sur le fichier "planet" conforme à la licence ODbL. Si la requête demande une date d'objet antérieur à ce que contient le fichier "planet", l'API Overpass renverra la première version de l'objet connu dans le fichier "planet" conforme à la licence ODbL.

Origine du nom : « Données archivées » se réfère aux données antérieures masquées dans la version actuelle de la base de données OSM. Le terme « Données historiques » n'est pas utilisé car ce n'est pas historique au sens d'un 'vieux château' ou similaire (jetez un oeil à OpenHistoricalMap ou sur cette conversation OSM-Talk), il s'agit plutôt de la notion « désapprouvée » ou « dépassé ».

Delta entre deux dates (diff)

La préférence diff permet de déterminer les changements dans la base de données à partir de deux requêtes à des moments différents dans le temps. Ceci est utile par exemple pour l'extraction d'écarts de bases de données.

Elle se compose du paramètre diff suivi de ":" et d'une spécification de date, optionellement d'une virgule suivi d'une deuxième date. Si une seule spécification de date est donnée, la seconde est supposée être l'état actuel.

Exemple:

  [diff:"2012-09-14T15:00:00Z"]
Cette écriture exécute le reste de la requête comme si elle était lancée le 14 Septembre 2012 à 15h00, puis réexécute la même requête sur les données actuelles, et sort finalement la différence entre les deux résultats.
  [diff:"2012-09-14T15:00:00Z","2012-09-21T15:00:00Z"]
C'est fondamentalement la même chose, mais on compare ici l'état du 14 Septembre avec celui du 21 Septembre.

Notez que la sortie ne comprend pas toutes les versions intermédiaires, qui peuvent exister entre le premier et le dernier horodatage, à savoir s'il y a plusieurs changements sur un objet, seule la dernière version dans la période donnée est renvoyée.

Delta commenté entre deux dates (adiff)

La préférence adiff fait essentiellement la même chose que diff, mais il est précisé ce qui est arrivé à tous les éléments qui ne figurent pas dans le résultat final.

Si un élément a été supprimé, sa date de suppression est sortie, ainsi que l'indication "visible=false". Si un élément a changé de telle sorte qu'il ne corresponde plus à la requête, sa dernière date de modification est sortie avec une indication "visible=true".

Pour plus d' informations, voir : Augmented Diffs.

Syntaxe spéciale

Commentaires

Le langage de requête permet des commentaires dans le même style comme dans le code source C :

  out; // Prend la fin de ligne en cours comme commentaire.
  /* Les commentaires commençant par slash étoile doivent toujours se fermer par étoile slash. */
  /* Mais ils peuvent s'étendre
       sur plusieurs lignes. */

Séquences d'échappement

Les séquences d'échappement suivantes du code C sont reconnues :

  • \n : échappe un retour chariot
  • \t : échappe une tabulation
  • \", \' : échappe la marque de guillemet correspondant
  • \\ : échappe un antislash
  • \u#### (les caractères "dièse" représentent quatre chiffres hexadécimaux) : échappe le caractère unicode UTF-16 correspondant, voir séquences d'échappement Unicode Unicode escape sequences.
    Notez que la base de données est encodée en caractères UTF-8 sur 1 octet (uniquement des caractères de la table US-ASCII dans les 7 bits de la gamme U+0000..U+007F) ou plus. Tous les caractères assignés à une valeur scalaire Unicode dans les tables 17 standards sont encodés en UTF-8.
    Mais cette syntaxe supporte seulement les caractères attribués dans le BMP ; à l' exclusion des substituts qui ne sont pas des caractères Unicode et n'ont pas encodage UTF-8 valide ; même s'ils ont une valeur scalaire de 16 bits. Les caractères non-ASCII dans le BMP sont encodés en UTF-8 sur 2 octets (dans la gamme U+0080..U+07FF), ou 3 octets (dans la gamme U+0800..U+FFFF, les substituts mineurs dans la gamme U+D800..U+DFFF).
    Les caractères Unicode hors BMP peuvent être représentés en UTF-16 comme une paire de substituts : seules les paires valides de substituts UTF-16 (un substitut majeur en U+D800..U+DBFF immédiatement suivi d'un substitut mineur en U+DC00..U+DFFF) sont convertibles en UTF-8 et peuvent être échappées par \uD###\uD### (le résultat d'échapper des paires invalides de substituts ou des substituts non appariés est indéfini) ; ces paires valides échappées de substituts seront converties en séquences encodées UTF-8 de 4 octets (dans des tableaux supplémentaires 1 à 15) ou 5 octets (dans le dernier plan supplémentaire valide 16 attribué uniquement pour un usage privé, non utile dans les données OSM tant qu'elles ne sont pas interopérables).
  • Il y a actuellement aucun support pour la syntaxe courante d'échappement \U000##### utilisé dans le C moderne pour représenter un marqueur dans l'une quelconque des 17 tables Unicode valides (hors substituts), même pas pour des octets arbitraires de 8 bits avec la syntaxe d'échappement courante \x## (défini en C indépendamment de l'encodage utilisé). L'échappement doit être évité autant que possible s'il n'est pas nécessaire, utilisez les UTF-8 valides directement dans les requêtes.

Dispositions expérimentales

Les dispositions décrites dans cette section ont été introduites en v0.7.51, mais ne sont pas encore entièrement testées et pas encore annoncées officiellement. Si vous rencontrez des bugs ou des problèmes, s'il vous plaît ouvrez un nouveau signalement Github.

Comptage des éléments (count)

En plus des modes output existants, out count; fournit un moyen pour renvoyer le nombre total d'éléments dans un lot d'entrée donné sans transférer les objets individuels OSM. Ceci est supporté en XML, JSON et en mode CSV.

out count;
Mode output XML
  <count total="923" nodes="923" ways="0" relations="0"/>
Mode output JSON
{
  "count": {
    "total": 923,
    "nodes": 923,
    "ways": 0,
    "relations": 0,
    "areas": 0
  }
}
Mode output CSV

En plus des champs de sortie décrits précédemment pour le mode output CSV, le comptage des éléments fournit des noms de champs supplémentaires spéciaux.

Nom de champ spécial Description
Les champs suivants sont remplis par une action out count;
 ::count Retourne le nombre total d'objets (nodes, ways, relations et areas) dans le lot d'entrée
 ::count:nodes Retourne le nombre de nodes dans le lot d'entrée
 ::count:ways Retourne le nombre de ways dans le lot d'entrée
 ::count:relations Retourne le nombre de relations dans le lot d'entrée
 ::count:areas Retourne le nombre d'areas dans le lot d'entrée

Cartographie des way/relation d'une zone (map_to_area)

Remarque : cette instruction pourrait encore changer à l'avenir.

L'instruction map_to_area cartographie les IDs des objets OSM pour les duos ways et relations en fonction de leur ID area virtuel de l'API Overpass.

Cela se fait en appliquant les règles de mappage suivantes à l'intérieur de l'API Overpass :

  • Pour les ways : ajouter 2.400.000.000 à l'ID OSM des ways.
  • Pour les relations : ajouter 3.600.000.000 à l'ID OSM des relations.

Exemple :

rel(62716);
out;              // sortie de la relation 62716
map_to_area;      // cartographie de la relation OSM dans l'area de l'API Overpass, en ajoutant 3.600.000.000 à son ID
out;              // sortie de l'area 3600062716
L'utilisation principale de cette instruction est de rechercher des objets à l'intérieur d'une zone, qui est elle-même dans une autre zone (zone dans une requête zone).

Note : La tâche interne à l'API Overpass de création de zone ne crée pas une zone pour chaque way/relation d'OSM. Si une zone n'existe pas pour un duo way/relation donné, map_to_area ignore simplement cet objet sans ajouter de zone.

Les exemples suivants décrivent certains cas possibles d'utilisation pour cette instruction :

Exemple 1 : Trouver tous les pubs dans le centre-ville de "Cologne"

area[name="Köln"]->.b;
rel(area.b)[name="Innenstadt"];
map_to_area -> .a;
node(area.a)[amenity=pub];
out meta;
Rechercher uniquement les areas nommée "Innenstadt" aurait renvoyé de nombreuses areas, sans se limiter à Cologne.

Exemple 2 : Trouver tous les comtés de "Hessen" sans caserne de pompiers

area[admin_level=4]["name"="Hessen"][boundary=administrative]->.boundaryarea;

( node(area.boundaryarea)["amenity"="fire_station"];
  way(area.boundaryarea)["amenity"="fire_station"];>;) ->.a;

.a is_in -> .b; 
area.b[admin_level=8] -> .bf; 

rel(area.boundaryarea)[admin_level=8];
map_to_area -> .bllf;

(.bllf - .bf ) ; 
rel(pivot); (._;>;); out;

Exemple 3 : Compter le nombre de pharmacies par comté

[out:csv(::"type",::"id", name, admin_level,::"count")];
area[name="Saarland"][boundary];
 rel(area)[boundary][admin_level=6];
 map_to_area;
 foreach->.d(
   (.d;);out; 
   (node(area.d)[amenity=pharmacy];
    way(area.d)[amenity=pharmacy];
    relation(area.d)[amenity=pharmacy];);
   out count;
 );