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 · Basa Sunda · Baso Minangkabau · bosanski · brezhoneg · català · čeština · corsu · 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 · română · shqip · slovenčina · slovenščina · Soomaaliga · suomi · svenska · Tagalog · 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) · Code source et problèmes · Site web

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.

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 de blocs. 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. 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 de sortie (out), qui est appelée une action, car cela fait sortir le résultat d'exécution. 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 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 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, voir : Par lot 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 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écursion simple en amont (<)

La requête autonome de récursion simple en amont 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 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 up.

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 :

  >>;

Requête des zones couvrantes (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 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 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[~"^$"~"."];              // trouver des nœuds avec un attribut de clé vide ("^$") et de n'importe quelle valeur non vide (".")
node[~"^$"~"^$"];             // trouver des nœuds avec un attribut de clé vide ("^$") et de 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 un tag 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 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 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 membres chemins du lot d'entrée
  rel(r);         // sélectionne les 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);


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, 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, 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), é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 :

  • le niveau de verbosité parmi les suivants (body est sélectionné par défaut) :
    • ids : sort seulement les IDs des éléments.
    • skel : sort aussi les informations 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.
    • 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.
    • count : sort seulement le comptage des éléments.
  • un des arguments suivants pour des informations dérivées (geom par défaut) :
    • 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>

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

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

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 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é.

Contrairement à l'instruction convert, on ne peut pas fixer de clé générique.

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.

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

  <Key> = <Evaluation>
  :: id = <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>

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]] )]
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 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; "|")];
format de sortie 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
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 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 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

Parmi les séquences d'échappement classiques du langage C, les séquences suivantes sont reconnues dans les requêtes Overpass :

  • \t : représente le caractère de contrôle de la tabulation (U+0009)
  • \n : représente le caractère de contrôle du saut de ligne (U+000A)
  • \", \' : 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 Wikipedia-16px.png 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

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.

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

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

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).
Notes
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.
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:...).

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

  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

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