FR:Overpass API/Overpass QL

API Overpass · Référence du langage · Guide du langage · Termes techniques · Aires · Exemples de requêtes · É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

Overpass Ultra · Examples · Overpass Ultra extensions · Feuilles de style MapLibre · URL Params · plus (français) · Code source et problèmes · Site web

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

Overpass QL (abréviation de "Overpass Query Language") est le deuxième langage de requête créé pour l'API Overpass ; le premier était Overpass XML.

Overpass QL est un langage de programmation procédural et impératif écrit avec une syntaxe de style C. Cette page wiki se veut une référence complète à la structure d'Overpass QL.

Aperçu du language

Déclarations

Le code source Overpass QL est divisé en instructions, et chaque instruction se termine par un point-virgule ;. Les instructions sont exécutées séquentiellement par un processus et chaque exécution d'instruction modifie l'état d'exécution du processus .

État d'exécution

L'état d'exécution Overpass QL comprend :

• l'ensemble par défaut _ (un seul trait de soulignement) ;
• d'autres ensembles nommés, s'ils ont été créés par l'utilisateur ;
• une pile, lors de l'exécution de blocs d'instructions Overpass QL.

Ensembles

Overpass QL manipule les ensembles. Les instructions écrivent leurs résultats dans des ensembles, puis les ensembles sont lus par les instructions suivantes en entrée. Un ensemble Overpass QL peut contenir n'importe quelle combinaison de — et n'importe quel nombre de — nœuds, voies, relations, and éléments de zone OpenStreetMap.

Sauf si vous spécifiez un ensemble nommé en tant qu'entrée ou résultat, toutes les entrées sont implicitement lues depuis (et tous les résultats sont écrits dans) l'ensemble par défaut nommé _ (un seul trait de soulignement). Une fois qu'un nouveau résultat est (implicitement ou explicitement) affecté à un ensemble existant, son contenu précédent sera remplacé et ne sera plus disponible. Les ensembles Overpass QL ont toujours une portée (visibilité) globale.

Par exemple :

  node[name="Foo"];

écrit implicitement le résultat de la balise query name="Foo" dans l'ensemble par défaut _, écrasant tout contenu précédent avec ce résultat. Un résultat peut être écrit dans un ensemble spécifique à l'aide de la syntaxe ->, lorsque ce nom d'ensemble est préfixé par .. L'instruction ci-dessus équivaut donc à :

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

De même, cette déclaration :

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

combine les résultats de deux requêtes de balises avec une instruction union, puis envoie ce résultat à l'ensemble par défaut _. Cela équivaut à :

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

Pour écrire des éléments dans un ensemble nommé, utilisez à nouveau la syntaxe ->, suivie du nom de l'ensemble. Par exemple, cette requête :

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

écrira tous les éléments du nœud avec la balise name=Foo dans l'ensemble nommé a. Les noms d'ensemble peuvent être constitués de lettres, de chiffres et du trait de soulignement ; cependant, ils ne doivent pas commencer par un chiffre. Pour lire des éléments d'un ensemble, ajoutez . et le nom d'ensemble pour la commande.

  node.a[amenity=foo];

renverra tous les nœuds de l'ensemble nommé a qui ont la clé amenity avec la valeur foo.

Structure du language

Il existe plusieurs types d'instructions Overpass QL. Elles sont regroupés en :

• Paramètres : qui sont des variables globales facultatives, définis dans la première instruction de la requête. Des exemples de paramètres sont le délai d'expiration de l'interrogation pour le serveur Overpass API et le format de sortie de la requête Overpass QL.
• Requêtes autonomes : ce sont des instructions complètes en elles-mêmes. Elles peuvent effectuer des fonctions telles que l'interrogation du serveur API Overpass pour créer un ensemble ; manipuler le contenu d'un ensemble existant ; ou l'envoi des résultats finaux d'une requête à un emplacement de sortie.
• Instructions de bloc : regroupement d'ensembles d'instructions Overpass QL, pour activer des disjonctions (tests de vérité), ainsi que des boucles.

Les requêtes autonomes sont elles-mêmes composées de plus petits composants du langage Overpass QL, tels que des évaluateurs, des filtres et des opérateurs.

Paramètres

Les paramètres Overpass QL doivent être déclarés dans la première instruction sans commentaire du code source Overpass QL. Les paramètres ne peuvent pas être déclarés dans plusieurs instructions.

Les déclarations de paramètres sont placées entre crochets []. Un deux-points : apparaît entre le nom du paramètre et la ou les valeurs à définir. L'instruction paramètres doit se terminer par un point-virgule ;.

// Ceci est une ligne de déclaration de paramètres typique
// sur un serveur Overpass Turbo
[out:json][timeout:25];

Durée maximale (timeout:)

Le paramètre timeout: a pour variable 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'abandonner par timeout. Le choix d'une valeur trop élevée est une autre 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 plus élevée, 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:)

Le paramètre maxsize: a pour variable 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 autre 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 le paramètre [out:...] et l'instruction out ...;. Leurs syntaxes ne doivent pas être mélangées.

Le paramètre out: définit le format de sortie des données OSM. Il 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]

Mode de sortie 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), des champs spéciaux sont disponibles pour chaque élément du jeu de résultats à afficher. Notez que tous ces noms de champs spéciaux doivent être préfixés par deux deux-points ::.

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 de métadonnées suivants sont disponibles seulement si l'action out meta; est utilisée pour générer des éléments OSM.
::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
Les champs de métadonnées suivants sont disponibles seulement si l'action out count; est utilisée pour générer des éléments OSM.
::count	Renvoie le nombre total d'objets (nœuds, voies, relations et zones) du jeu d'entrées
::count:nodes	Renvoie le nombre de nœuds du jeu d'entrées
::count:ways	Renvoie le nombre de voies du jeu d'entrées
::count:relations	Renvoie le nombre de relations du jeu d'entrées
::count:areas	Renvoie le nombre de zones du jeu d'entrées

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"];
  (nwr(area)[railway=station];
  out;

Ligne d'en-tête CSV

La présence ou l'absence d'une 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. La valeur par défaut est true.

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

Caractère séparateur de champs CSV

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 pipe ("|").

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

Vérification de la complétion des données pour la sortie CSV

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 suivant étend la liste précédemment affichée de toutes les gares de Bonn par l'ajout d'une instruction de sortie 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;

Le résultat inclut désormais une colonne supplémentaire avec le type ::count et une indication sur le nombre total d'éléments contenus dans le lot de résultat actuel : 5. Si la ligne finale de décompte est manquante ou que le nombre total différe, 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	0		5

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

Boîte de sélection globale (bbox:)

Le paramètre bbox: définit la boîte englobante qui sera ensuite implicitement utilisée dans toutes les instructions (sauf si une instruction spécifie une bbox explicite différente). La boîte englobante globale par défaut si aucune bbox n'est spécifiée est "le monde entier".

Dans un programme Overpass QL standard, une boîte englobante est construite avec deux paires de coordonnées en degrés décimaux dans l'ordre et le format standard ISO 6709, et chaque valeur est séparée par une virgule. Les valeurs sont dans l'ordre : latitude la plus au sud, longitude la plus à l'ouest, latitude la plus au nord, longitude la plus à l'est.

[bbox:south,west,north,east]
// Une bbox encadrant la ville allemande de Bonn
[bbox:50.6,7.0,50.8,7.3]
// Une bbox encadrant une partie de Rio de Janeiro, Brésil
[bbox:-23,-43.1,-22.8,-43.3]

Remarque : Si la requête Overpass est passée dans une URL avec une valeur dans son paramètre data=, un cadre de sélection peut également être ajouté en tant que variable bbox distinct. L'ordre des coordonnées est alors inversé lon-lat (cet ordre est celui utilisé par OpenLayers et d'autres frameworks).

L'exemple ci-dessous trouve toutes les boîtes aux lettres de la zone de Bonn, en Allemagne :

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

Données archivées (date)

Le paramètre global date modifie une requête Overpass QL pour examiner les antiquités de données de la base de données OpenStreetMap, et renvoyer les résultats à la date spécifiée. Ce paramètre peut être utile, par exemple, pour reconstruire des données qui ont été vandalisées, ou simplement pour afficher un objet tel qu'il existait dans la base de données à un moment donné dans le passé.

Il se compose de l'identifiant date, suivie de : puis d'une date standard ISO 8601 de la base de données OpenStreetMap entre guillemets, au format YYYY-MM-DDThh:mm:ssZ.

Cet exemple interroge l'état de la base de données le 28 octobre 2015 à 19:20:00 UTC :

[date:"2015-10-28T19:20:00Z"]

Limitation : Il n'y a pas d'antiquité des données dans la base de données OpenStreetMap avec une date antérieure au 2012-09-12T06:55:00Z (1347432900 en secondes d'époque). Cette date correspond à la première modification incluse dans le fichier planète compatible ODbL. L'utilisation d'un paramètre date antérieur est techniquement possible, mais cela renverra toujours l'état de la base de données au 2012-09-12T06:55:00Z.

Delta entre deux dates (diff)

Le paramètre diff permet de déterminer les changements dans la base de données à partir de deux requêtes temporelles différentes. Ceci est utile par exemple pour l'extraction d'écarts de bases de données.

Il se compose de l'identifiant diff, suivi de :, d'une date de la base de données OpenStreetMap entre guillemets au standard ISO 8601, format YYYY-MM-DDThh:mm:ssZ, et éventuellement d'une virgule et d'une deuxième date par défaut à la date actuelle ("maintenant").

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 génère 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)

Le paramètre 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.

Instructions de blocs

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.

Différence

La déclaration d'un opérateur différence se fait sous forme d'une paire de parenthèses "( )". Dans un opérateur différence 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 différence 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 :

  node.a.b;

La méthode est décrite plus bas, voir : Par lot d'entrée (.setname).

Instruction de bloc if

depuis v0.7.55

L'instruction de bloc if exécute ses sous-instructions uniquement si sa condition est évaluée comme booléen true. Cela permet par exemple d'essayer des conditions de recherche plus lâches si des conditions de recherche trop strictes n'ont pas donné de résultat.

L'instruction n'interagit pas directement avec les ensembles.

La syntaxe de base est

 if (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }

et intégralement

 if (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }
 else
 {
   <Liste des sous-déclarations>
 }

où <Évaluateur> est un évaluateur et <Liste des sous-déclarations> est une liste de sous-déclarations.

Boucle for-each (foreach)

depuis v0.7.51

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 des opérateurs union ou foreach.

Il faut un lot d'entrée. Il n'y a pas de génération d'un lot résultat. L'instruction foreach boucle une fois pour chaque élément du lot d'entrée. 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.

Instruction de bloc for

depuis v0.7.55

L'instruction de bloc for divise son entrée en sous-ensembles et exécute toutes les instructions du corps de boucle une fois pour chaque sous-ensemble.

L'ensemble d'entrées se décompose comme suit : Pour chaque élément, l'évaluateur donné est évalué et les éléments de même valeur sont regroupés. Au début de chaque exécution de boucle, l'ensemble de sortie est rempli avec le sous-ensemble correspondant.

La syntaxe de base est

 for (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }

Le jeu d'entrée et de sortie peut être spécifié entre for et la parenthèse ouvrante, c'est-à-dire que vous définissez le jeu d'entrée

 for.<Nom de l'ensemble d'entrée> (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }

ou l'ensemble de sortie

 for->.<Nom de l'ensemble de sortie> (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }

ou les deux

 for.<Nom de l'ensemble d'entrée>->.<Nom de l'ensemble de sortie> (<Évaluateur>)
 {
   <Liste des sous-déclarations>
 }

Dans la boucle, la valeur de l'évaluateur est disponible via la propriété val de l'ensemble de sortie. C'est-à-dire, avec

 <ensemble de sortie>.val

vous pouvez accéder à la valeur de l'expression pour cette boucle.

Avec les évaluations spéciales keys() , on peut boucler sur toutes les clés qui existent dans le sous-ensemble. Les sous-ensembles respectifs pour chaque clé sont les éléments qui ont cet ensemble de clés. Contrairement à un évaluateur habituel, les ensembles ne sont pas mutuellement distincts dans ce cas.

Instruction de bloc complete

depuis v0.7.55

L'instruction de bloc complete parcourt ses sous-instructions jusqu'à ce que les résultats de la boucle se stabilisent. Cela permet de suivre un groupe d'éléments peu ou pas connectés, comme toutes les sections d'un chemin du même nom ou un système de rivières tributaires.

L'instruction fournit les éléments accumulés dans son jeu de sortie à la fois au début de chaque exécution de boucle et en tant que sortie de l'instruction entière.

Les éléments sont accumulés à partir de l'ensemble d'entrée avant d'entrer dans la boucle et à nouveau à partir de l'ensemble d'entrée à la fin de la boucle. Si l'ensemble d'entrée contient des éléments supplémentaires, la boucle est à nouveau exécutée.

La syntaxe de base est

 complete
 {
   <Liste des sous-déclarations>
 }

où <Liste des sous-déclarations> est une liste de sous-déclarations.

Le nombre maximal de boucles par défaut est de 4096. Cette valeur peut être remplacée par n'importe quelle valeur comprise entre 1 et 1048576 pour cette boucle. Pour ce faire, mettez la valeur souhaitée entre parenthèses après le mot clé complete :

 complete(<Number>)
 {
   <Liste des sous-déclarations>
 }

Le jeu d'entrée et de sortie peut être spécifié entre complete et la parenthèse ouvrante, c'est-à-dire que vous définissez le jeu d'entrée

 complete.<Nom du jeu d'entrée>
 {
   <Liste des sous-déclarations>
 }

ou l'ensemble de sortie

 complete->.<Nom du jeu de sortie>
 {
   <Liste des sous-déclarations>
 }

ou les deux

 complete.<Nom de l'ensemble d'entrée>->.<Nom de l'ensemble de sortie>
 {
   <Liste des sous-déclarations>
 }

et intégralement

 complete(<Number>).<Nom du jeu d'entrée>->.<Nom du jeu de sortie>
 {
   <Liste des sous-déclarations>
 }

Instruction de bloc retro

depuis v0.7.55

L'instruction de bloc retro exécute ses sous-instructions pour la date indiquée dans l'évaluateur.

Il n'est actuellement pas défini si le contenu des variables extérieures au bloc est disponible dans le bloc et vice versa. Les versions futures peuvent transférer uniquement des éléments dérivés, garder les environnements complètement séparés ou transformer des éléments d'un point à l'autre.

La syntaxe de base est

 retro (<Évaluateur>)
{
  <Liste des sous-déclarations>
}

où <Évaluateur> est un évaporateur et <Liste des sous-déclarations> est une liste de sous-déclarations.

Instruction de bloc compare

depuis v0.7.55

L'instruction compare calcule le diff des données de deux horodatages. Ce diff peut être composé de n'importe quel élément ainsi que de ceux ayant des propriétés spécifiques.

L'instruction peut avoir un bloc de sous-déclarations. Le bloc de sous-instructions est exécuté après avoir calculé le diff lors de la deuxième exécution, une fois pour l'ancien horodatage, puis à nouveau pour le nouvel horodatage. Cela permet de faire des calculs supplémentaires en fonction des résultats diff.

L'instruction ne peut être utilisée qu'en mode diff. Dans d'autres modes, son comportement n'est pas défini, et dans les versions futures, il pourrait donner une erreur de syntaxe elsewhere.

Dans la première exécution d'une requête diff, il renvoie un ensemble vide. Dans la deuxième exécution d'une requête diff, il renvoie la différence des éléments. Si l'instruction obtient un évaluateur comme argument, seuls les éléments ayant des valeurs différentes sur les deux horodatages sont renvoyés. Si l'élément n'existe pas sur l'un des horodatages, sa valeur est considérée comme la chaîne vide. Actuellement, le seul but d'une telle différence est de l'intégrer dans une instruction de sortie.

La syntaxe de base est

compare();

De plus, un ensemble d'entrée et/ou de sortie peut être spécifié :

.<Set> compare()->.<Set>;

Avec l'évaluateur, la syntaxe devient

compare(delta:<Evaluateur>);

et intégralement

.<Set> compare->.<Set>(delta:<Evaluateur>);

Dans toutes les variantes de syntaxe, un bloc de sous-instructions peut être attaché :

compare()
 {
  <Liste des sous-déclarations>
 };

ou intégralement

.<Set> compare(delta:<Evaluateur>)->.<Set>;
 {
  <Liste des sous-déclarations>
 };

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 sûr 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 :

  nwr["name"~"^Foo"];        // tout ce qui commence par "Foo"
  nwr["name"~"Foo$"];        // tout ce qui se termine par "Foo"
  nwr["name"~"^Foo$"];       // trouve exactement "Foo"
  nwr["name"~"Foo"];         // tout ce qui contient "Foo"
  nwr["name"~"."];           // tous les objets avec la clé "name". Équivalent à nwr["name"];
  nwr["name"!~"."];          // tous les objets sans la clé "name". Équivalent à nwr[!"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 chemins), 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);

Les identifiants des zones (areas) sont dérivés d'un chemin (way) OSM en ajoutant 2 400 000 000 à son identifiant, ou d'une relation en ajoutant 3 600 000 000 à son identifiant. Attention ! En raison de la forte croissante des données OSM, ces valeurs devront changer en 2022 ou 2023 afin d'éviter des conflits. Préférez la fonction map_to_area pour éviter ces calculs.

La création des zones (areas) est définie par des règles d'extraction. Seuls certains types de chemins et de relations sont doublés d'une zone. 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 "newer:" dans certains cas. Pensez à utiliser "newer:" 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;

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 "Nom de clé" s'il 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 même priorité.

Leur syntaxe est :

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

L'espace est facultatif.

• Si au moins un argument n'est pas un nombre, le résultat est "NaN" (Not a Number = pas un nombre).
• Le résultat est sinon un nombre à virgule flottante à l'exception de la multiplication de deux nombres entiers qui donne un entier.

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.

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

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

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

rel(62716)->.b;
  .b out;
  .b map_to_area;
  out;

Voir aussi

• Un cours de l'université de Rennes 2 sur le requétage avec Overpass