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 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 API logo.svg
API Overpass · Référence du langage · Guide du langage · Termes techniques · Aires · Exemples de requêtes · Exemples avancés · Édition clairsemée · ID persistant · Questions fréquentes · plus (français) · Site web
État des serveurs · Versions · Développement · Conception technique · Installation · Surcouche de compatibilité XAPI · Diagrammes de transports publics · Applications · Code source et problèmes
Overpass turbo · Assistant · Raccourcis Overpass turbo · Feuilles de style MapCSS · Export en GeoJSON · plus (français) · Développement · Code source et problèmes · Site web

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

Contents

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 d'opérateurs. Un lot de données peut contenir des nœuds (nodes), des chemins (ways), des relations et des zones (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. À 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 de sortie (out), qui est appelée une action, car cela fait sortir le résultat d'exécution. Les autres instructions sont regroupées 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 d'opérateurs : ces instructions traitent des regroupements et permettent des conditions ainsi que des boucles.
  • Préférences : ce sont les choses qui peuvent être définies 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 "_". Exemple :

  node[name="Foo"];

Une sortie peut être envoyée à un lot spécifique, en utilisant la syntaxe "->" et en préfixant le lot avec ".". La requête ci-dessus est donc équivalente à :

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

Dans la même logique, la requête :

 (
  node[name="Foo"];
  node[name="Bar"];
 );

combine les sorties des deux requêtes et l'envoie aussi dans "_". Ce qui équivaut à :

 (
  node[name="Foo"];
  node[name="Bar"];
 )->._;

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

  (node[name="Foo"];)->.a;
stockera tous les nodes avec une clé name=Foo dans le lot "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 d'opérateurs

Union

La déclaration d'un opérateur union se fait sous forme d'une paire de parenthèses "( )". Dans un opérateur union tout type d'instruction peut être utilisé, y compris des déclarations imbriquées d'opérateurs union ou de boucles foreach. Notez que les crochets [...] indiqués ci-dessous signalent une partie optionnelle de la syntaxe et ne doivent pas être saisis littéralement.

  (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 opérateur difference se fait sous forme d'une paire de parenthèses "( )". Dans un opérateur difference on ne peut mettre que deux instructions séparées par un signe moins. Notez que les crochets [...] indiqués ci-dessous signalent une partie optionnelle de la syntaxe et ne doivent pas être saisis littéralement.

  (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 d'opérateur. La méthode est décrite plus bas, voir : Par lot d'entrée (.setname).

Boucle for-each (foreach)

La déclaration d'un opérateur foreach se fait par le nom de l'instruction suivi d'une paire de parenthèses "foreach( )". Tout type d'instruction peut être utilisé entre ces parenthèses, y compris des déclarations imbriquées de opérateurs 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 Récursion simple en aval.

  (._; >;);

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.

Récursions

Pourquoi nous avons besoin de récursion

En général, nous sommes intéressés par des jeux de données complets, c'est-à-dire pas simplement les nœuds, ou pas simplement les chemins, ou pas simplement les relations, mais de tous les types si ceux-ci constituent un jeu de données consistant. De plus, il serait dommage de tronquer un jeu de données si celui-ci est à la limite d'une boîte de recherche, ou au contraire il est préférable de retirer certaines données complétement plutôt que de les récupérer tronquées ... Par exemple que faire des nœuds en dehors de la boîte de recherche, si ceux-ci appartiennent à un chemin qui se trouve partiellement dans la boîte de recherche ?

La même question se pose pour les relations. Si par exemple, votre boîte de recherche se situe à la limite de la frontière avec la Russie, il est probable que vous ne vouliez pas de milliers de kilomètres de frontières russes...

Les récursions sont là pour ceci, vous laisser le choix d'inclure ou d'exclure les objets qui sont à la limite, ceci pour avoir un ensemble résultat soit plus petit, soit plus grand, mais dans tous les cas consistant.

Récursion simple en amont (<)

La requête autonome de récursion simple en amont (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 chemins qui ont un nœud apparaissant dans le lot d'entrée, plus
  • toutes les relations qui ont un nœud ou chemin apparaissant dans le lot d'entrée, plus
  • toutes les relations qui ont un chemin 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;

Récursion multiple des relations en amont (<<)

La requête autonome de récursion multiple des relations en amont a une syntaxe similaire à la requête de récursion simple en amont 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 de récursion multiple des relations en amont retourne la fermeture transitive et réflexive en sens inverse des appartenances de membres.

Exemple :

  <<;

Récursion simple en aval (>)

La requête autonome de récursion simple en aval (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 nœuds qui font partie d'un chemin apparaissant dans le lot d'entrée, plus
  • tous les nœuds ou chemins qui sont membres d'une relation apparaissant dans le lot d'entrée, plus
  • tous les nœuds qui font partie d'un chemin 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 de récursion en amont.

Exemple :

  >;

Récursion multiple des relations en aval (>>)

La requête autonome de récursion multiple des relations en aval a une syntaxe similaire à la requête de récursion simple en aval 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 down.

Précisément, la requête autonome de récursion multiple des relations en aval retourne la fermeture transitive et réflexive des appartenances de membres.

Exemple :

  >>;

Zone englobante (is_in)

La requête autonome is_in renvoie les zones (areas : polygones fermés générés par l'API Overpass) qui couvrent

  • les coordonnées données (lorsque spécifié) ou
  • les nœuds 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 nœuds 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 :

(les [crochets] indiquent des éléments optionnels qui ne sont pas imposés dans la syntaxe à saisir)

  [.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 nœuds 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 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, chacun indiqués entre [crochets] ou (parenthèses) selon leur nature.

Exemple :

// filtres simples
  node[name="Foo"];
  way[name="Foo"];
  rel[name="Foo"];
  area[name="Foo"];

// filtres combinés
  node[name="Foo"][type="Bar"];
node, way, rel et 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 attribut (has-kv)

Le filtre has-kv sélectionne tous les éléments qui ont ou n'ont pas un attribut avec une clé spécifiée et optionellement avec une certaine valeur. Il supporte les objets basiques d'OSM de type nœud (node), chemin (way) et relation, ainsi que l'objet étendu zone (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 attribut avec la clé donnée mais pas la valeur correspondante, ou les éléments qui n'ont pas d'attribut avec la clé donnée.

Égalité (=, !=)

Cette condition, la plus commune, sélectionne tous les éléments qui ont un attribut 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 les nœuds ayant l'attribut de clé "name" contenant la valeur exacte "Foo"
  node[name=Foo];
  node['name'="Foo"];
  node[name="Foo"];
  node["name"='Foo'];
  node["name"!='Foo']; // trouve les nœuds ayant l'attribut de clé "name" ne contenant pas la valeur exacte 'Foo'

Si vous devez mentionner des espaces, des signes de ponctuation (comme ":") ou caractères spéciaux (réservés par la syntaxe) dans le nom d'une clé ou dans une valeur, vous devez l'encadrer par des guillemets simples ou doubles ; les guillemets sont facultatifs s'il n'y a que des lettres (même accentuées ou dans des écritures non latines), des chiffres ou le symbole de soulignement "_" :

  node["name"="Boulevard de Montréal"];
  node["name"='Boulevard de Montréal'];
  node[name="Boulevard de Montréal"];

  node[name="Angoulême"];
  node[name='Angoulême'];
  node[name=Angoulême];

  node["admin_level"="8"];
  node['admin_level'='8'];
  node[admin_level=8];

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 attributs ayant une clé vide n'est pas possible par égalité simple, mais nécessite l'utilisation d'une expression régulière pour cette clé spéciale (non recommandée).

node[~"^$"~"."];              // trouve les nœuds avec un attribut de clé vide ("^$") et valeur non vide (".") quelconque
node[~"^$"~"^$"];             // trouve les nœuds avec un attribut de clé vide ("^$") et valeur vide ("^$")

N.b. : 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 attribut 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

depuis v0.7.53

Cette variante sélectionne tous les éléments, qui n'ont pas d'attribut avec une clé particulière de contenu quelconque.

  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 attribut 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 le couple clé et valeur correspond à une expression régulière. Après le ~ (tilde) initial l'expression régulière pour la clé doit être fourni, 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
  node[~"^name(:.*)?$"~"."];     // trouve tags "name" ou "name:lang", quel que soit son contenu
  node[~"^name(:ar|:he)?$"~"."]; // trouve tags "name", "name:ar" ou "name:he", 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 rectangle de délimitation (bbox)

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

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

Récursion (n, w, r, bn, bw, br)

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

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 de l'un des symboles w (à l'aval de chemins), r (à l'aval de relations), bn (à l'amont de nœuds), bw (à l'amont de nœuds), ou br (à l'amont de relations), puis une déclaration optionnelle d'un lot d'entrée, et se termine par une parenthèse fermante.

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

  node(w);        // sélectionne les nœuds enfants depuis les chemins du lot d'entrée
  node(r);        // sélectionne les nœuds membres de relations du lot d'entrée
  way(bn);        // sélectionne les chemins parents pour les nœuds du lot d'entrée
  way(r);         // sélectionne les chemins membres des relations du lot d'entrée
  rel(bn);        // sélectionne les relations qui ont des nœuds membres du lot d'entrée
  rel(bw);        // sélectionne les relations qui ont des chemins membres du lot d'entrée
  rel(r);         // sélectionne les relations membres des relations du lot d'entrée
  rel(br);        // sélectionne les relations parentes des relations du lot d'entrée

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

  node(w.foo);    // sélectionne les nœuds enfants des chemins du lot d'entrée "foo"

Hormis le cas de la récursion des nœuds d'un chemin (où ils n'ont aucun rôle associé), vous pouvez aussi limiter la récursion à un rôle spécifique des membres de relations parentes. Il suffit d'ajouter ":" (deux points) et le nom du rôle avant la parenthèse fermante.

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

  node(r:"rôle"); // sélectionne tous les nœuds qui sont membres, avec le rôle "rôle", des relations parentes du lot d'entrée
  way(r:"rôle");  // sélectionne tous les chemins qui sont membres, avec le rôle "rôle", des relations parentes du lot d'entrée
  rel(bn:"rôle"); // sélectionne tous les relations parentes qui ont pour membres, avec le rôle "rôle", des nœuds du lot d'entrée 
  rel(bw:"rôle"); // sélectionne tous les relations parentes qui ont pour membres, avec le rôle "rôle", des chemins du lot d'entrée
  rel(r:"rôle");  // sélectionne tous les relations qui sont membres, avec le rôle "rôle", des relations parentes du lot d'entrée
  rel(br:"rôle"); // sélectionne tous les relations parentes qui ont pour membres, avec le rôle "rôle", des relations du lot d'entrée

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

  node(r.foo:"rôle"); // sélectionne tous les nœuds qui sont membres, avec le rôle "rôle", des relations parentes du lot d'entrée "foo"

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

  node(r:"");     // sélectionne tous les nœuds qui sont membres, avec le rôle vide, des relations parentes du lot d'entrée par défaut
  node(r.foo:""); // sélectionne tous les nœuds qui sont membres, avec le rôle vide, des relations parentes du lot d'entrée "foo"

Par lot d'entrée (.setname)

Ce filtre se compose de l'instruction item (un simple point), suivi du nom du 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.

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

  node._;         // requête équivalente à "node;"
ou avec le lot nommé "a".
  node.a;

Il est aussi possible de désigner plusieurs lots d'entrée (intersection des lots).

  node.a.b;

Cette instruction renvoie tous les nœuds qui sont à la fois dans les lots d'entrées "a" et "b".

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

Le filtre id-query sélectionne l'élément de type voulu avec l'identifiant donné. Il supporte les types de données OSM nœud (node), chemin (way), relation, et aussi zone (area).

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 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 le noeud ayant id=1
  way(1);
  rel(1);
  area(1);

Notez que les identifiants des zones (areas) doivent être dérivés d'un chemin (way) OSM existant en ajoutant 2 400 000 000 à son identifiant OSM, ou d'une relation OSM existante en ajoutant 3 600 000 000 à son identifiant OSM. Cela conduit à certaines contraintes d'extraction des zones (areas), à savoir : tous les chemins/relations ont une zone en doublon. Voir areas.osm3s pour plus de détails.

Depuis la version 0.7.54, le filtre id-query supporte aussi les valeurs multiples. Pour éviter les conflits avec le filtre bbox, un nouveau code obligatoire id: doit être utilisé dans ce cas.

  node(id:1000,1001,1002,1003,1004,1005);
  way(id:3998029,3998240,4065354,4065364,4065392,4065421);
  rel(id:10815,10816);
  area(id:1234);

Optimisation performance : Essayez de regrouper plusieurs requêtes d'identifiants en une seule instruction, c'est à dire au lieu d'écrire (way(3998029);way(3998240);way(4065354);); utilisez plutôt way(id:3998029,3998240,4065354);.

Autour de (around:)

Le filtre around sélectionne tous les éléments dans un certain rayon autour des éléments du lot d'entrée. Si vous fournissez des coordonnées, celles-ci sont utilisées à la place du lot d'entré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 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 lot 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 lot d'entrée par défaut :

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

Exemples, avec un lot 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 nœuds "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;

Trouvez à la fois les nœuds "cinéma" et les chemins à Bonn, à une distance maximale de 100 m des nœuds d'arrêt de bus :

  area[name="Bonn"];
  node(area)[highway=bus_stop]->.bus_stops;
  (
    way(around.bus_stops:100)[amenity=cinema];
    node(around.bus_stops:100)[amenity=cinema];
  );
  (._;>;);
  out meta;

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 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 du mot poly, d'un signe deux-points, 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 en Allemagne :

  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 et que la différence de date est au maximum d'un mois, alors le filtre changed est probablement un meilleur choix que newer.

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), 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 (voir note), d'autre part cela peut être appliqué comme filtre unique.

Remarque : À compter de juin 2017, un bogue connu peut faire que "changed:" soit beaucoup plus lent que "never:" dans certains cas. Pensez à utiliser "never:" jusqu'à ce que ce soit résolu, ou envisagez de tester celui qui fonctionne le plus vite pour vous. Voir les tickets Github suivants : #278, #322, #346. Voir aussi cette discussion.

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), éventuellement suivie d'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'à 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. Si le nom d'utilisateur comprend des espaces ou caractères spéciaux, il doit être encadré de guillemets simples ou doubles. Les guillemets ne sont pas nécessaires pour les identifiants dont la valeur est un simple entier décimal.

Exemple :

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

Depuis la version 0.7.53, il est également possible de spécifier plusieurs noms ou identifiants 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 lot 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);

Notez que area(area); n'est actuellement pas pris en charge. Dans ce cas, le filtre (area) sera ignoré silencieusement, conduisant à des résultats inattendus en retournant toutes les zones présentes dans le lot d'entrée.

Les zones (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'identifiant de zone peut être calculé à partir d'un chemin OSM existant en ajoutant 2 400 000 000 à son identifiant 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 : tous les chemins et relations d'OSM n'ont pas forcement une zone associée (notamment ceux qui sont marqués avec l'attribut area=no, et la plupart des multipolygones qui n'ont pas de name=* défini et ne correspondent pas à une zone fermée).

Les zones sont créées par une tâche différée 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 retournée pour 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 méthode dans votre requête : utilisez les identifiants des éléments standard d'OSM et filtrez les par les attributs 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 lot 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;

Requête conditionnelle (if:)

depuis v0.7.54

Le filtre requête conditionnelle peut être ajouté à une instruction de requête. Il dispose d'une évaluation parametrée et ne laisse passer que les éléments pour lesquels la réponse est l'expression booléenne « vrai ».

Pour le moment, le filtre de requête ne peut pas être la condition unique d'une requête. Cela est dû à des raisons d'implémentation et devrait changer dans les futures versions.

Il est techniquement possible d'avoir plusieurs requêtes conditionnelles dans une simple requête. Mais cela n'a pas de sens :

  • Leurs évaluations peuvent être imbriquée avec la conjonction d'un seul filtre de requête.
  • C'est la même sémantique et c'est plus rapide.

La syntaxe est :

  (if: <Evaluation>)

L'espace est facultative.

De nombreux filtres ci-dessus peuvent être généralisés en utilisant un filtre de requête conditionnelle, si l'on a besoin de conditions bien particulières pour filtrer les objets dans le lot d'entrée de la requête. Par exemple, la requête :

  node[name=foo];

est équivalente à la suivante qui utilise un filtre de requête conditionnelle (mais par simplification l'usage de l'ancienne syntaxe qui utilise un simple filtre par valeur d'attribut est préférable, car cela peut avoir de meilleures performances sur le serveur Overpass, et que la nouvelle syntaxe des évaluations peut ne pas toujours être supportée dans l'implémentation actuelle des serveurs et bibliothèques clientes Overpass avant la version 0.7.54 de l'API) :

  node(if: t["name"] == "foo");

Actions

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

Sortie des données (out)

L'instruction out s'exé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.

L'instruction 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 final.

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

  • un niveau de verbosité parmi les suivants (sélection body défaut) :
    • ids : sort seulement les IDs des éléments.
    • skel : sort aussi les informations minimum nécessaires pour la géométrie. Ce sont entre autres les coordonnées des nœuds, des chemins, la liste ordonnée des identifiants des nœuds membres de chemins ou la liste des types et identifiants des éléments membres de relations.
    • body : sort toutes les informations nécessaires pour utiliser les données. Ce sont entre autres les attributs (clés et valeurs) de tous les éléments et les rôles des membres de relation.
    • tags : sort seulement les identifiants et attributs de chaque élément sans les coordonnées des membres (ce sont les seules informations disponibles à partir d'éléments dérivés générés par des instructions "make" ou "convert", tels les attributs géométriques des nodes, et les éléments de contenu des ways et des relations sont absentes).
    • meta : sort toutes les informations associées aux éléments. Cela complète la sortie body en incluant pour chaque élément son numéro de version, l'identifiant du groupe de modifications (changeset), son horodatage, et des données pour identifier le dernier utilisateur qui a touché l'élément (notez que ces métadonnées d'attributs manquent également pour les éléments dérivés générés par des instructions "make" ou "convert").
    • count : sort seulement le comptage des éléments.
  • un des arguments suivants pour des informations géolocalisées, geom par défaut. (notez que cette information est manquante pour les éléments dérivés créés par des instructions spéciales "make" ou "convert") :
    • geom : ajoute la géométrie complète à chaque objet. Cela ajoute les coordonnées à chaque nœud, ainsi qu'à chaque nœud membre d'un chemin ou d'une relation, et ajoute une liste de membres nd avec leurs coordonnées à toutes les relations.
    • bb : ajoute la boite de sélection de chaque élément à ces éléments. Pour les nœuds ceci est équivalent à geom. Pour les chemins c'est la boite de sélection englobant tous leurs nœuds. Pour les relations, c'est la boîte de sélection englobant tous les nœuds et chemins membres, sans que cela s'applique aux relations membres.
    • center : ajoute le centre de la boite de sélection mentionnée ci-dessus aux chemins' et relations. Note : il n'est pas garanti que le point central se trouve à l'intérieur du polygone si ce dernier n'est pas convexe (exemple).
  • une boite de sélection au format (sud,ouest,nord,est) (normalement utilisée avec le paramètre geom). 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 chemins les coordonnées du nœud qui précèdent l'entrée dans la boite de sélection ou qui suit la sortie de la boite de sélection sont fournies 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 : trier dans l'ordre numérique des identifiants d'objet.
    • qt : trier par index quantile ; ce qui est à peu près géographique et nettement plus rapide que le classement par identifiant.
  • un nombre entier positif indiquant le nombre maximum d'éléments à sortir (sans limite par défaut).
Exemple Instruction out
sort les éléments du lot d'entrée par défaut sans leurs métadonnées out;
sort les éléments avec leurs métadonnées out meta;
sort jusqu'à 99 éléments out 99;
sort jusqu'à 1 000 000 éléments, triés géographiquement, avec leurs métadonnées out meta qt 1000000;
sort les éléments du lot d'entrée "a" sans leurs métadonnées .a out;

Comptage des éléments (out count)

En plus des modes de sortie 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é pour les formats de sortie XML, JSON et CSV.

  out count;
Format de sortie XML
  <count total="923" nodes="923" ways="0" relations="0"/>
Format de sortie JSON
{
  "count": {
    "total": 923,
    "nodes": 923,
    "ways": 0,
    "relations": 0,
    "areas": 0
  }
}

Instructions produisant des éléments dérivés

depuis v0.7.54

TODO: Améliorer la définition de ce qu'est cet « élément dérivé ».

Les éléments dérivés sont des éléments artificiels qui peuvent être créés à partir de données existantes d'OSM, de certaines propriétés statistiques ou même de valeurs constantes.

Contrairement aux objets OSM communs (tels que les nœuds, les voies et les relations), il n'est pas possible de créer des métadonnées complètes à partir de tels éléments dérivés, à savoir qu'il n'est pas possible de générer des éléments avec des valeurs lat/lon, utilisateur, uid, numéro de version ou horodatage dernière modification. Ceci permet d'éviter les modifications automatisées qui réinjecteraient des éléments OSM ré étiquetés.

Conversion (convert)

depuis v0.7.54

L'instruction convert retourne un élément dérivé par élément de son lot d'entrée. Le contenu de ce lot résultat est contrôlé par les paramètres de l'instruction.

Il est nécessaire de définir un « type » valable pour tous les éléments générés, ensuite un nombre variable d'attributs peut être paramétré (certains en utilisant des évaluations).

De plus, il est possible de définir explicitement l'id des objets générés. Si vous ne définissez pas cet id, un identifiant unique est attribué selon une numérotation globale ascendante.

Enfin, on peut l'utiliser pour copier toutes les clés de l'objet d'origine. Dans ce cas, il est également possible de supprimer sélectivement certains attributs.

La syntaxe de base est :

  convert <type> <Liste d'attributs>
  convert.<Input Set> <Type> <List of Tags>

avec le lot d'entrée par défaut "_" , ou avec <Liste d'attributs> comme liste d'items séparés par des virgules, dont chacun doit être l'une des opérations suivantes :

  :: id = <Evaluation>
  :: = <Evaluation>
  <Key> = <Evaluation>
  ! <Key>

Dans la liste ci-dessus, seules les métadonnées ::id sont générées (en tant qu'attributs) dans l'élément dérivé. En version 0.7.54, les objets dérivés n'incluent pas encore d'informations géométriques. Cela devrait changer dans une future version.

Tous les autres métadonnées attributs d'éléments (tels que l'identifiant de ChangeSet, le numéro de version, le nom de l'utilisateur ou son identifiant, l'horodatage, normalement fixés pour tous les éléments de la base de données d'OSM avec un identifiant positif défini) ne sont pas spécifiés pour l'élément dérivé. Ceci est fait pour empêcher les traitements de masse automatisés.

Constitution (make)

depuis v0.7.54

L'exécution de l'instruction make produit un élément dérivé. Le contenu de cet élément de sortie est contrôlé par les paramètres de l'instruction et ne doit être redondant avec un élément de la base de données OSM.

Cette instruction est le plus souvent utilisé pour générer des rapports d'état ou d'analyse simplifiés (par agrégation de données de base) plus petits à télécharger et plus facile/rapide à traiter dans des applications clientes, avec juste quelques attributs d'un (ou très peu) éléments.

Il est nécessaire de définir un « type » valable pour tous les éléments générés, libre de choix. Ensuite un nombre variable d'attributs peut être défini (en utilisant des évaluateurs).

Contrairement à l'instruction convert on ne peut pas fixer de clé générique, car l' instruction convert ne prend aucun lot d'entrées (et elle n'a pas d'entrée par défaut à mentionner dans les évaluateurs).

Enfin, il est possible de définir explicitement l'id de l'objet généré. Si vous ne définissez pas cet id, un identifiant unique est attribué selon une numérotation globale ascendante.

Toutes les autres métadonnées attributs d'éléments (tels que l'ID de changeset, le numéro de version, le nom d'utilisateur ou son ID, l'horodatage, normalement définis pour tous les éléments de la base de données OSM avec un ID positif défini) ne sont pas spécifiés pour l'élément dérivé. En outre, il n'existe aucun moyen de spécifier autre chose que des attributs pour un élément dérivé. En particulier, cela inclut la géométrie et les membres (comme dans le cas des ways ou des relations).

La syntaxe de base est :

  make <Type> <Liste d'attributs>

où <Liste d'attributs> est une liste d'items séparés par des virgules, dont chacun doit être l'une des opérations suivantes

  :: id = <Evaluation>
  <Key> = <Evaluation>

Exemple :

  make my_element_name                                    // utiliser le type my_element_name
       ::id = 1234,                                       // définir l'id de l'élément résultant
       "attribut1" = "ceci est la valeur de l'attribut1", // ajoute attribut1 avec une constante chaîne
       "attribut2" = 4711,                                // ajoute attribut2 avec une valeur numérique
       "attribut3" = date("2018-07-01");   // ajoute attribut3 avec une valeur renvoyée en appelant une fonction

  out;

Résultat :

 <?xml version="1.0" encoding="UTF-8"?>
 <osm version="0.6" generator="Overpass API"> 
 <note>The data included in this document is from www.openstreetmap.org. The data is made available under ODbL.</note>
 <meta osm_base="2017-03-11T12:55:02Z"/>

  <my_element_name id="1234">
    <tag k="attribut1" v="ceci est la valeur de l'attribut1"/>
    <tag k="attribut2" v="4711"/>
    <tag k="attribut3" v="2018.439453125"/>
  </my_element_name>

</osm>

Evaluations

depuis v0.7.54

Les évaluations sont des opérateurs de construction qui restituent une valeur à leur exécution. L'usage de ce que les évaluations fabriquent dépend du contexte.

Les évaluations peuvent aider à filtrer les éléments d'une requête. Elles peuvent fournir des informations statistiques sur les résultats de la requête. Elles permettent aussi de supprimer ou d'ajouter des attributs aux éléments.

Actuellement, seules les évaluations d'attributs sont prises en charge. Les évaluations de géométrie sont prévus mais pas encore implémentés.

Les types suivants d'évaluations existent et sont expliquées ci-dessous :

  • Les évaluations de constantes délivrent toujours la même valeur indépendamment du contexte.
  • Les évaluations de dépendance d'élément délivrent des informations sur un objet individuel. Elles n'ont un sens que dans le contexte d'un élément unique.
  • Les évaluations statistiques fournissent des informations sur l'ensemble d'un lot.
  • Les agrégateurs exécutent une boucle d'évaluation sur l'ensemble des éléments d'un lot et combinent ce qui en résulte.
  • Les opérateurs et endomorphismes combinent le résultat d'une ou deux évaluations déjà exécutées dans un nouveau résultat.

L'ordre de préséance est le suivant, de forte à faible contrainte :

  • Évaluateurs atomiques :
    • Valeurs
    • Évaluateurs entre parenthèses
    • Opérateurs d'éléments dépendants
    • Endomorphismes
    • Évaluateurs statistiques ou agrégateurs
  • Opérateurs unaires :
    • Négation arithmétique
    • Négation booléenne
  • Opérateurs binaires :
    • Multiplication et division
    • Addition et soustraction
    • Plus petit que, Plus petit ou égal à, Plus grand que, Plus grand ou égal à
    • Égalité, comparaisons d'inégalités
    • Conjonction booléenne
    • Disjonction booléenne

Valeur fixe

depuis v0.7.54

Cet opérateur retourne toujours une valeur fixe. Il ne prend aucun argument.

Sa syntaxe est :

  <Valeur>
  • Les valeurs fixes peuvent être des chaînes de caractères, des entiers ou des nombres à virgule flottante.
  • Les valeurs fixes sont utilisées comme opérandes dans les évaluateurs.

Opérateurs d'éléments dépendants

depuis v0.7.54

Les opérateurs d'élément dépendants requièrent un ou aucun paramètre.

Leur syntaxe varie, mais la plupart ont l'apparence d'un nom de fonction suivi de parenthèses.

Ils ne peuvent être appelés que dans le contexte où les éléments sont traités. Cela vaut pour convert, pour filtrer, ou pour les arguments des agrégateurs.

Ils ne peuvent pas être appelés directement depuis make.

Id et type

depuis v0.7.54

Ces opérateurs s'appliquent implicitement à chaque élément sélectionné dans le jeu d'entrée courant. Les deux ne prennent aucun paramètre.

L'opérateur id renvoie l'identifiant de l'élément sous la forme d'un entier.

Sa syntaxe est :

  id()
  • Les nodes, ways et relations ont les ids de la base de données OSM.
  • Les éléments de type area ont un identifiant virtuel interne généré par le serveur Overpass.
  • Les éléments dérivés créés dans la requête elle-même par les instructions make ou convert n'ont pas d'id défini.

L'opérateur type renvoie le type d'élément sous forme d'une chaîne de caractères : node, way, relation, area ou derived.

Sa syntaxe est :

  type()

Valeurs d'attributs, vérification de valeur d'attribut, et valeurs génériques

depuis v0.7.54

L'opérateurs tag renvoie la valeur de la clé donnée.

Sa syntaxe est :

  t[<Nom de clé>]

L'opérateur is_tag renvoie "1" si l'élément donné a une clé avec cette variable et "0" dans les autres cas.

Sa syntaxe est :

  is_tag(<Nom de clé>)
  • Ils ne peuvent être appelés que dans le contexte d'un élément.
  • Le <Nom de clé> doit figurer entre guillemets "Non de clé" s'il contient des caractères spéciaux.

Le <nom clé> doit être entre guillemets si elle contient des caractères spéciaux.

L'opérateur tag générique renvoie la valeur de l'étiquette de la clé pour laquelle il a été lancé.

Sa syntaxe est :

  ::
  • Il ne peut être appelé que dans le contexte d'un élément.
  • De plus, il doit faire partie de la valeur d'une propriété générique pour avoir sa clé spécifiée.

Comptage de caractéristiques d'un élément

depuis v0.7.54

Cette variante de l'opérateur count compte des attributs ou des membres de l'élément donné. Par opposition à la variante statistique de l'opérateur count, elle ne peut pas prendre un lot d'entrée.

La syntaxe du compteur d'attribut est :

  count_tags()

La syntaxe du compteur de membres est :

  count_members()

Exemple :

Trouver des ways composés de seulement deux nœuds :

  [bbox:{{bbox}}];
  way(if:count_members() == 2);
  out geom;

Trouvez des relations sans aucun attribut et seulement un seul élément (=node/way/relation) :

  [bbox:{{bbox}}];
  rel(if:count_members() == 1 && count_tags() == 0);
  out ;

Agrégateurs

depuis v0.7.54

Les agrégateurs ont besoin simultanément pour fonctionner, du lot de données et d'un évaluateur comme argument.

L'évaluateur boucle sur chaque élément du lot, et l'agrégateur combine les résultats en une simple valeur.

Union et lots

depuis v0.7.54

Ces agrégateurs exécutent l'évaluation notée à leur droite sur chaque élément du lot.

L'agrégateur u renvoie la valeur unique trouvée si une valeur non vide est retournée lors de l'évaluation de chaque élément du lot spécifié :

  • Si aucune valeur est trouvé alors u retourne une chaîne vide.
  • Si plusieurs valeurs différentes sont trouvées alors u renvoie le texte de diagnostic « <plusieurs valeurs trouvées> ».

Sa syntaxe est :

  <Lot>.u(<Evaluateur>)

Si le lot est la valeur par défaut "_", alors vous pouvez vous dispenser du paramètre lot :

  u(<Evaluateur>)

L' agrégateur de lot renvoie une liste séparée par des points-virgules ";" (sans ordre particulier) de toutes les valeurs distinctes non vides qui apparaissent ; cette chaîne retournée peut être potentiellement très longue, et éventuellement tronquée si une limite interne est atteinte.

Sa syntaxe est :

  <Lot>.set(<Evaluateur>)

Si le lot est la valeur par défaut "_", alors vous pouvez vous dispenser du paramètre lot :

  set(<Evaluateur>)

Minimum et Maximum

depuis v0.7.54

Ces agrégateurs exécutent l'évaluation notée à leur droite sur chaque élément du lot.

Leur syntaxe est :

  <Lot>.min(<Evaluateur>)
  <Lot>.max(<Evaluateur>)

Si le lot est la valeur par défaut "_", alors vous pouvez vous dispenser du paramètre lot :

  min(<Evaluateur>)
  max(<Evaluateur>)

Ces deux agrégateurs exécutent l'évaluation notée à leur droite sur chaque élément du lot spécifié :

  • Si toutes les valeurs retournées sont des nombres valides, alors min renvoie le minimum parmi les nombres. De même, si toutes les valeurs retournées sont des nombres valides, max renvoie le maximum parmi les nombres.
  • Si aucune valeur n'est un nombre valide, alors min renvoie la première chaîne lexicographique. De même, si toutes les valeurs retournées ne sont pas valides, max renvoie la dernière chaîne lexicographique.
  • Si aucune valeur n'est trouvée, min et max retournent une chaîne vide.

Somme

depuis v0.7.54

Cet agrégateurs exécute l'évaluation notée à sa droite sur chaque élément du lot spécifié :

Sa syntaxe est :

  <Lot>.sum(<Evaluateur>)

Si le lot est la valeur par défaut "_", alors vous pouvez vous dispenser du paramètre lot :

  sum(<Evaluateur>)
  • Si toutes les valeurs retournées sont valides, alors sum renvoie leur somme.
  • En d'autres termes, sum renvoie "NaN".

Comptage statistique

depuis v0.7.54

Cette variante de l'opérateur count compte les éléments d'un type donné dans un lot.

Sa syntaxe est :

  <Lot>.count(nodes)
  <Lot>.count(ways)
  <Lot>.count(relations)
  <Lot>.count(deriveds)       // par exemple pour les zones ''areas''

Si le lot est la valeur par défaut "_", alors vous pouvez vous dispenser du paramètre lot :

  count(nodes)
  count(ways)
  count(relations)
  count(deriveds)


Opérateurs unaires

Les opérateurs unaires ont besoin d'un seul opérande pour leur exécution. Ils sont toujours écrits en préfixe de l'expression.

Leur syntaxe est :

  <Opérateur><Evaluateur>

Les opérateurs peuvent être regroupés avec des parenthèses.

  (<Opérateur><Evaluateur>)

Les parenthèse peuvent être utilisées pour remplacer la priorité de l'opérateur.

Négation booléenne

depuis v0.7.54

La négation booléenne est évaluée à "0" si son argument est évalué comme le booléen "faux". Sinon, elle est évaluée à "1".

Sa syntaxe est :

  ! <Evaluateur>

L'espace est facultative.

  • Une chaîne vide et toute chaîne qui représente numériquement un zéro représente le booléen "faux".
  • Toute autre chaîne représente le booléen "vrai".

Négation arithmétique

depuis v0.7.54

L'opérateur "-" (moins) effectue une négation arithmétique de son argument.

Sa syntaxe est :

  - <Evaluateur>

L'espace est facultative.

  • Si l'argument est un nombre entier, le résultat est un nombre entier.
  • Si l'argument est un nombre à virgule flottante, le résultat est un nombre à virgule flottante.
  • Sinon, le résultat est "NaN".

Endomorphismes de chaine de caractères

depuis v0.7.54

Les endomorphismes de chaînes sont des fonctions qui acceptent un argument de type chaîne et retournent une autre chaîne. Ils évaluent toujours leur argument.

Leur syntaxe est :

  <Nom de la fonction>(<Evaluateur>)

Beaucoup d'entre eux aident à normaliser ou vérifier la valeur de l'argument. Pour l'instant ils sont seulement de ce genre, limités à l'évaluation des nombres et des dates.

Des fonctions supplémentaires peuvent être définies plus tard (telles que la normalisation Unicode ou les transformations de casse), mais peuvent nécessiter des paramètres supplémentaires (auquel cas elles ne seraient plus des endomorphismes).

Vérification et normalisation nombre

depuis v0.7.54

La fonction number transforme son argument en un nombre normalisé.

Sa syntaxe est :

  number(<Evaluateur>)
  • Si l'argument n'est pas un nombre, alors number renvoie "NaN".

La fonction is_number vérifie si son argument est un nombre. Elle renvoie "1" si son argument peut être analysé comme un nombre et "0" dans les autres cas.

Sa syntaxe est :

  is_number(<Evaluateur>)

Date de vérification et de normalisation

depuis v0.7.54

La fonction date transforme son argument en un nombre représentant une date.

Sa syntaxe est :

  date(<Evaluateur>)
  • Si l'argument n'est pas une date, date retourne "NaD" (pas de date).

La fonction is_date vérifie si son argument représente une date. Elle renvoie "1" si l'argument peut être analysé comme une date et "0" dans les autres cas.

Sa syntaxe est :

  is_date(<Evaluateur>)

Une chaîne est analysée pour une date comme suit :

  • Le premier groupe de chiffres est compris comme une année.
  • Le groupe de chiffres suivant, s'il est présent, est compris comme un mois.
  • Le groupe suivant, s'il est présent, est compris comme un jour.
  • Si d'autres groupes de chiffres sont présents, ils sont compris comme heures, minutes et secondes, dans cet ordre.

Pour être une date valide :

  • L'année doit être supérieure à 1000,
  • Le mois, s'il est présent, doit être inférieur ou égal à 12,
  • Le jour, s'il est présent, doit être inférieur ou égal à 31,
  • L'heure, si elle est présente, doit être inférieure ou égale à 60,
  • Les minutes et secondes, si elles sont présentes, doivent être inférieures ou égales à 60.

L'analyseur de date pourrait être plus ouvert dans les futures versions et accepter plus de représentations de dates.

La requête suivante peut être utilisée comme illustration de la conversion d'attributs "start_date" en valeurs de date numériques.

[bbox:{{bbox}}];

node[start_date];      // recherche tous les nœuds avec l'attribut "start_date" dans la zone de délimitation courante

convert elem                               // converti les nœuds du lot d'entrée en <elem> 
    ::id = id(),                           // garde l'identifiant des nœuds
    original_date = t[start_date],         // trouve valeur dans l'attribut "start_date"
    normalized_date = date(t[start_date]), // converti "start_date" en valeur numérique
    is_date = is_date(t[start_date]);      // "start_date" est-elle une date reconnue ?

out;                   // Affiche les résultats de l'instruction ''convert''

Opérateurs binaires

depuis v0.7.54

Les opérateurs binaires ont besoin de deux opérandes pour fonctionner. Ils sont toujours écrits en notation infixée.

Leur syntaxe est :

  <Evaluateur><Opérateur><Evaluateur>

Les opérateurs peuvent être regroupés avec des parenthèses.

  (<Evaluateur><Opérateur><Evaluateur>)

Les parenthèses peuvent être utilisées pour remplacer la priorité d'un opérateur :

  2 + 3 * 4           // Est évalué à 2 + 12, soit = 14
  (2 + 3) * 4         // Alors qu'avec parenthèses l'évaluation est 5 * 4 , soit 20

Multiplication et Division

depuis v0.7.54

Les opérateurs de multiplication et de division effectuent les opérations arithmétiques respectives. Ils ont la même priorité.

Leur syntaxe est :

  <Evaluateur> * <Evaluateur>
  <Evaluateur> / <Evaluateur>

L'espace est facultatif.

  • Si un ou les deux arguments ne sont pas numérotés, le résultat est "NaN".
  • Les opérateurs sont traités comme des nombres à virgule flottante à l'exception de la multiplication de deux nombres entiers.

Addition et Soustraction

depuis v0.7.54

Les opérateurs d'addition et de soustraction effectuent les opérations arithmétiques respectives. Ils ont la même priorité.

Leur syntaxe est :

  <Evaluateur> + <Evaluateur>
  <Evaluateur> - <Evaluateur>

L'espace est facultatif.

  • Si les deux arguments peuvent être interprétés comme des entiers, ils sont ajoutés ou soustraits comme des entiers.
  • Sinon, si les deux arguments peuvent être interprétés comme des nombres à virgule flottante, ils sont ajoutés ou soustraits en tant que nombres à virgule flottante.
  • Dans tous les autres cas, l'opérateur "+" concatène les arguments en tant que chaînes et l'opérateur "-" renvoie "NaN".

Le "-" unaire est un opérateur distinct de l'opérateur binaire "-" défini ici. Il a une priorité plus élevée.

Plus petit que, Plus petit ou égal, Plus grand et Plus grand ou égal

depuis v0.7.54

Ces opérateurs s'affiche à "1" si leurs arguments se comparent respectivement. Sinon, ils s'affiche à "0".

La syntaxe pour ces opérateurs est :

  <Evaluateur> <  <Evaluateur>
  <Evaluateur> <= <Evaluateur>
  <Evaluateur> >  <Evaluateur>
  <Evaluator>  >= <Evaluateur>

L'espace est facultatif.

  • Si les deux arguments peuvent être interprétés comme des entiers, leurs valeurs sont comparées comme des entiers.
  • Sinon, si les deux arguments peuvent être interprétés comme des nombres à virgule flottante, leurs valeurs sont comparées sous forme de nombres à virgule flottante.
  • Dans tous les autres cas, les valeurs sont comparées lexicographiquement en tant que chaînes.

Égalité et Inégalité

depuis v0.7.54

L'opérateur d'égalité s'affiche à "1" si ses deux arguments sont égaux. Sinon, il s'affiche à "0".

Sa syntaxe est :

  <Evaluateur> ==  <Evaluateur>

L'espace est facultatif.


L'opérateur d'inégalité s'affiche à "0" si ses deux arguments sont égaux. Sinon, il s'affiche à "1".

et sa syntaxe est :

  <Evaluateur> !=  <Evaluateur>

L'espace est facultatif.

  • Si les deux arguments peuvent être interprétés comme des entiers, leurs valeurs sont comparées comme des entiers.
  • Sinon, si les deux arguments peuvent être interprétés comme des nombres à virgule flottante, les valeurs sont comparées sous forme de nombres à virgule flottante.
  • Dans tous les autres cas, les valeurs sont comparées en tant que chaînes.

Conjonction booléenne et Disjonction

depuis v0.7.54

La conjonction booléenne s'affiche à "1" si ses deux arguments sont évalués à une valeur booléenne "vrai". Sinon, il s'affiche à "0".

Sa syntaxe est :

  <Evaluateur> &&  <Evaluateur>

L'espace est facultatif.


La disjonction booléenne s'affiche à "1" si l'un ou l'autre de ses arguments est évalué à une valeur booléenne "vrai". Sinon, il s'affiche à "0".

Sa syntaxe est :

  <Evaluateur> ||  <Evaluateur>

L'espace est facultatif.

  • Une chaîne vide et chaque chaîne qui est une représentation numérique d'un zéro représente un booléen "faux".
  • Toute autre chaîne représente un booléen "vrai".

Actuellement, les deux arguments sont toujours évalués. Cela pourrait changer dans les versions futures.

Préférences d'exécution

Les préférences d'exécution sont indiquées en tête de requête avant la première instruction. Elles sont indiquées, dans un ordre quelconque, chacune encadrée entre [crochets], sous forme d'un mot-clé, d'un deux-points avant leur paramètre.

Durée maximale (timeout:)

La préférence timeout: a pour paramètre 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 paramètre 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'instruction 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 le format geoJSON)
  • csv
  • custom
  • popup

La valeur par défaut est xml.

Exemple :

  [out:json]

Personnalisation du format CSV

Le format de sortie csv renvoie 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]] )]

Remarques :

  • Les valeurs numériques (coordonnées, ids) n'utilisent pas de séparateur de milliers et utilisent le point anglais (.) comme séparateur décimal.
  • Aucun symbole d'échappement n'est inséré pour les caractères spéciaux des valeurs type chaîne de caractères. Cela devrait changer avec la version 0.7.55.
  • Le caractère séparateur par défaut (tabulation) doit toujours permettre d'analyser les données tabulaires sans colonnes manquantes/cassées ou mal alignées.
  • Ces options CSV par défaut peuvent ne pas toujours correspondre à ce que votre application de tableur prévoit (notamment le séparateur décimal dans les versions non anglaises). Parfois, lorsque vous ouvrez le fichier CSV directement avec cette application, les données semblent corrompues ou non analysable : en ce cas, importez les données dans une colonne texte d'une nouvelle feuille de calcul, et reformatez ces données en tableau dans cette application d'après vos propres paramètres ; ou utilisez un script externe de filtrage pour convertir le fichier avant de l'ouvrir.
Liste des noms de champs

En plus des noms de champs OSM normaux (attributs), les champs spéciaux suivants (attributs métadonnées et coordonnées) sont disponibles pour chaque élément du lot résultat à produire :

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 "::" (un double 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; "|")];

Comptage en mode out:csv

En plus des champs de sortie décrits précédemment pour le mode out: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

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 :

L'exemple suivant étend la liste précédemment affichée de toutes les gares de Bonn par l'ajout d'une instruction out retournant une ligne agrégée additionnelle dans le CSV, qui decrit un pseudo-élément de type "count" dont la valeur dans la colonne sera celle dans la dernière requête "::count" (sur cette ligne, les colonnes de données normales reste vides) :

  [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 la colonne @type et une indication sur le nombre total d'éléments contenus dans le lot de résultat actuel. Si la ligne finale de décompte est manquante ou que le nombre total différé, vous saurez avec certitude que quelque chose s'est mal déroulé, et que les résultats de la requête sont incomplets/incohérents :

@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 de sortie 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 par un filtre).

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 (tel que défini dans la norme ISO 6709).

  [bbox:sud,ouest,nord,est]

Exemple, impose un cadre de recherche correspondant à peu près à la ville allemande de Bonn (coordonnées : 50.7°N 7.15°E) :

  [bbox:50.6,7.0,50.8,7.3]

Si la requête Overpass est passée dans une URL par son paramètre data=, les coordonnées de la boîte peuvent également être précisée dans un paramètre bbox= séparé de celui de la requête (dont la préférence indiquée bbox n'aura aucun paramètre). L'ordre des coordonnées est alors inversé en longitude ouest, latitude sud, longitude est, latitude nord (cet ordre est celui utilisé par OpenLayers et d'autres frameworks).

Exemple, cette requête trouve toutes les boîtes aux lettres de la zone de Bonn, en Allemagne :

  /api/interpreter?bbox=7.0,50.6,7.3,50.8&data=[bbox];node[amenity=post_box];out;

  // Requête équivalente avec la préférence globale d'exécution :
  /api/interpreter?data=[bbox:50.6,7.0,50.8,7.3];node[amenity=post_box];out;

  // Requête équivalente sans préférence mais avec un filtre local :
  /api/interpreter?data=node(bbox:50.6,7.0,50.8,7.3)[amenity=post_box];out;

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 les codes sources C, C++, Javascript ou CSS :

  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, classiques du langage C (également définies en Javascript) pour la reconnaissance de caractères, sont reconnues :

  • \n : représente le caractère de contrôle du saut de ligne (U+000A)
  • \t : représente le caractère de contrôle de la tabulation (U+0009)
  • \", \' : représente la marque de guillemet ou l'apostrophe ASCII correspondante
  • \\ : représente un antislash
  • \u#### (les symboles dièse sont quatre chiffres hexadécimaux) : représente un caractère Unicode du plan multilingue de base avec son point de code sur 16 bits - consulter Utilisation des séquences d'échappement Unicode dans les chaînes.
Notez que la base de données encode tous les textes en UTF-8, sur 1 à 4 octets par caractère (seuls les caractères de la gamme U+0000..U+007F, correspondant au jeu ASCII sur 7 bits, sont codés sur 1 seul octet). Tous les points de code Unicode assignés à une valeur scalaire dans l'un des 17 plans standards peuvent être encodés en UTF-8 (même les non-caractères bien que leur utilisation dans la base de données OSM devrait être évitée, de même que la plupart des caractères de contrôle ASCII hormis les deux ci-dessus).
Mais cette syntaxe supporte seulement les caractères attribués dans le plan multilingue de base (à l'exclusion des substituts utilisés pour le codage UTF-16, 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 plan multilingue de base sont encodés en UTF-8 sur 2 octets (dans la gamme U+0080..U+07FF), ou 3 octets (dans la gamme U+0800..D7FF ou U+E000..U+FFFF).
Les caractères Unicode hors du plan multilingue de base (dans la gamme U+10000..U+10FFFF) peuvent être représentés en hexadécimal sous forme d'une paire de substituts : seules les paires valides de substituts UTF-16 (un substitut majeur en \uD800..\uDBFF immédiatement suivi d'un substitut mineur en \uDC00..\uDFFF) sont convertibles en UTF-8 et peuvent être codées par \uD###\uD### (la chaîne de caractères en UTF-8 qui serait obtenue par cette représentation mais sous forme de paires invalides de substituts, ou avec des substituts non appariés est indéfinie) ; les paires de substituts valides seront converties en séquences encodées UTF-8 de 4 octets (dans un des plans Unicode supplémentaires 1 à 16).
Les caractères qui ne sont attribués que pour un usage privé (ceux des deux derniers plans supplémentaires 15 et 16 dans la gamme U+E0000..U+10FFFF, ainsi que ceux du plan multilingue de base dans la gamme U+E000..U+F8FF) ne sont pas utiles dans les données OSM car ils ne sont pas interopérables. De même les points de code valides attribués à des non-caractères (tels que U+###FE et U+###FF) devraient être évités (même s'ils ont des représentations UTF-8 et UTF-16 valides) pour des raisons de compatibilité avec le code applicatif.

Il y a actuellement aucun support pour la syntaxe courante d'échappement \U000##### utilisé en langage C moderne pour représenter un point de code (hors substituts) de l'un quelconque des 17 plans Unicode valides, 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 nativement utilisé pour le texte).

L'échappement doit être évité autant que possible s'il n'est pas nécessaire pour la syntaxe Overpass, codez directement le texte en UTF-8 valide dans les requêtes.

Le serveur de la base de données OSM ne rejette toujours pas les textes contenant des séquences UTF-8 invalides (et certains de ces textes invalides persistent encore dans la base de données) : certains anciens éditeurs pour OSM et outils d'importation utilisaient d'autres codages pour le texte (par exemple la page de code Windows 1252) en omettant de le convertir en UTF-8, ce qui a conduit à des textes altérés (parfois invalides en UTF-8 et qui ne peuvent être recherchés avec Overpass qu'au moyen de séquences d'échappement ou d'expressions régulières compliquées).

Dispositions expérimentales

Conversion d'un chemin ou d'une relation OSM en zone Overpass (map_to_area)

L'instruction map_to_area fait correspondre les chemins et relations OSM à leur identifiant de zone (area) dans la base de données Overpass.

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

  • Pour les zones représentées par des chemins fermés (ways)  : ajouter 2 400 000 000 à l'identifiant de chemin OSM.
  • Pour les zones représentées par des relations dont les chemins membres délimitent la zone : ajouter 3 600 000 000 à l'identifiant de relation OSM.

Exemple :

  rel(62716);
  out;              // sortie de la relation 62716
  map_to_area;      // fait correspondre la relation OSM à l'area de l'API Overpass, en ajoutant 3 600 000 000 à son identifiant OSM
  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).

Remarques 
  • La tâche interne à l'API Overpass de création de zones (areas) ne crée pas une zone pour chaque chemin fermé ou relation d'OSM, mais ne le fait qu'en fonction de certains attributs (zone nommée, identifiant de référence, et certains types d'objets pouvant couvrir des surfaces étendues clairement identifiées et délimitées utiles aux recherches par zone, telles que les frontières administratives). Si une zone n'a pas été créée dans la base de données Overpass pour un chemin fermé ou une relation OSM donné (par exemple un simple bâtiment), map_to_area ignore simplement cet objet sans ajouter de zone au lot de résultat.
  • L'utilisation des zones dans les requêtes au lieu d'éléments OSM réels peuvent accélérer les requêtes Overpass. Les zones d'Overpass permettent de précalculer la géométrie et d'unifier les recherches en utilisant des géométries (multi)polygonales précalculées pour des recherches sur les zones les plus courantes.
  • Pour effectuer des recherches sur des zones très peu étendues, il est plus efficace de le faire avec un simple filtre de cadre de délimitation (bbox:...) ou à proximité d'une position donnée avec (around:...).
  • De plus, toutes les relations et tous les chemins ne peuvent pas être convertis en une zone valide (même si leurs balises impliquent normalement qu'elles doivent être des zones valides) si elles ne créent pas de périmètre correctement fermés.


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

try it yourself in overpass-turbo
area[name="Köln"]->.b;
rel(area.b)[name="Innenstadt"];
map_to_area -> .a;
node(area.a)[amenity=pub];
out meta;
Rechercher uniquement les zones nommée "Innenstadt" aurait renvoyé de nombreuses zones de centre-villes (ainsi nommées en allemand), sans se limiter à la seule ville de Cologne.

Exemple 2 : trouver tous les arrondissements de la Hesse sans caserne de pompiers

try it yourself in overpass-turbo
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 arrondissement dans la Sarre

try it yourself in overpass-turbo
[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;
 );

Exemple 4ː Lot d'entrée défini

try it yourself in overpass-turbo
rel(62716)->.b;
  .b out;
  .b map_to_area;
  out;