Wikidata:Accès aux données
|
Wikidata pour les développeurs:accès aux données |
Wikidata contient actuellement plus de 110 millions d'éléments et plus de 1,3 milions de lexèmes, et ces chiffres continuent d'augmenter. Il existe plusieurs moyens d’accéder aux données ; ce document les présente et aide les utilisateurs potentiels à choisir la méthode d’accès la mieux adaptée à leurs besoins.
Il est essentiel de sélectionner la méthode qui vous donne accès aux données de la manière la plus rapide et la plus efficiente possible, sans exiger plus de ressources que nécessaire des serveurs de Wikidata. Cette page a pour but de vous aider en ce sens.
Avant de commencer
Utiliser les données de Wikidata
Wikidata offre un large spectre de données générales sur tout ce qu'il est possible d'imaginer. Toutes ces données sont publiées sous licence CC0, « aucun droit réservé », pour le domaine public.
Les modifications faites aux API et aux autres moyens d’accès aux données utilisés pour accéder à Wikidata sont soumises aux règles des interfaces stables (Politique d'interface stable) . Il n’est pas garanti que les sources de données présentes sur cette page soient des interfaces stables.
Projets Wikimédia
Ce document parle des moyens d’accès aux données depuis les projets externes à Wikimedia. Si vous voulez utiliser les données de Wikidata dans un autre projet Wikimédia où il est possible d’utiliser des fonctions d’analyse, du code Lua ou d’autres méthodes internes au projet uniquement, voyez Comment utiliser les données sur les projets Wikimedia.
Bonnes pratiques de réutilisation des données
Nous mettons à disposition les données de Wikidata gratuitement et sans obligation de mention de la licence CC-0. En contrepartie, nous vous serions reconnaissant si vous mentionnez dans votre projet que vos données proviennent de Wikidata. De ce fait, vous permettez à Wikidata de rester en ligne et de continuer à fournir des données à jour et de haute qualité. Nous mettons aussi en avant les meilleurs projets utilisant les données de Wikidata.
Voici quelques exemples de texte permettant d’indiquer la provenance des données : « Propulsé par Wikidata », « Powered by Wikidata », « Utilise des données provenant de Wikidata », « Source : Wikidata », « Origine des données : Wikidata », etc. Vous pouvez également utiliser l’une de nos images immédiates.
Vous pouvez utiliser le logo Wikidata affiché ci-dessus, à condition de le faire d'une manière qui n'implique pas directement Wikidata ou la Fondation Wikimédia.
Si possible, donnez à vos utilisateurs la possibilité de reporter les problèmes dans les données et de les transmettre à la communauté des éditeurs de Wikidata, par exemple avec l’outil Mismatch Finder. Veuillez mentionner sur la discussion du projet, l'endroit où vous avez rencontré ces problèmes.
Bonnes pratiques de l’accès aux données
Lorsque vous utilisez les données provenant de Wikidata, merci de suivre ces bonnes pratiques :
- Suivez la politique d'agent utilisateur – envoyez la bonne en-tête d'agent utilisateur.
- Suivez la politique des robots : envoyez
Accept-Encoding: gzip,deflateet ne faites pas trop de demandes en parallèle. - Si vous recevez une réponse 429 Requêtes trop nombreuses (Too Many Requests), arrêtez d'envoyer d'autres requêtes pendant un certain temps (voir l'en-tête de réponse Réessayer-Après).
- Si disponible (comme avec le service de requêtes Wikidata), définissez le délai le plus court qui a du sens pour vos données.
- Lorsque vous utilisez l'API Action de MediaWiki, utilisez librement le paramètre
maxlaget consultez le reste des instructions présentées dans API:Etiquette.
Fonction recherche
De quoi s’agit-il ?
Wikidata met à disposition un index Elasticsearch pour les recherches traditionnelles à travers ses données : Special:Search
Quand l'utiliser ?
Utilisez cet outil lorsque vous cherchez une chaîne de caractère ou lorsque vous savez quel élément vous cherchez mais ne connaissez pas son identifiant. Il peut également permettre des recherches basées sur des relations très simples entre les données.
Il n’est en revanche pas adapté à la recherche de relations plus complexes entre les données.
Détails
Nous pouvons rendre notre recherche plus performante en lui ajoutant ces mots clé spécifiques à Wikidata : haswbstatement, inlabel, wbstatementquantity, hasdescription, haslabel. Cette fonctionnalité de recherche est documentée sur la page de l'extension CirrusSearch. Elle possède également sa propre API action.
Interface des données liées (URI)
Qu'est-ce que c'est ?
L'interface des données liées fournit un accès aux entités individuelles via l'URI : http://www.wikidata.org/entity/Q???. Ces URI sont appelés URI conceptuels. Notez que ces derniers utilisent HTTP, et non HTTPS.
Quand l'utiliser ?
Utilisez l'interface de données liées lorsque vous avez besoin d'obtenir des entités individuelles et complètes qui vous sont déjà connues.
Ne l'utilisez pas lorsque vous ne savez pas exactement de quelles entités vous avez besoin – essayez d'abord de chercher ou de faire des requêtes. Il n'est pas non plus adapté pour demander une grande quantité de données.
Détails
Chaque élément ou propriété possède un URI persistant qui est composé de l'espace de nom de concept Wikidata, et de l'ID de l'Item ou de la Property (par exemple Q42, P31) et des données concrètes qui peuvent être consultées à l'aide de l'URL des données de cet élément ou propriété.
L'espace de noms des données Wikidata concernant les entités est https://wikidata.org/wiki/Special:EntityData.
Ajouter un identifiant d'entité à ce préfixe génère une URL abstraite (elle ne correspond à aucun format spécifique) de l'URL de données de l'entité. Lorsque vous accédez à une ressource de l'espace de noms Special:EntityData, la page spéciale applique la négociation du contenu pour déterminer le format des données de sortie. En affichant les données dans un navigateur, vous verrez une page HTML contenant les données de l'entité car les navigateurs web préférent le HTML. Néanmoins les clients qui traitent les données recevront les données d'entité au format JSON ou RDF en fonction de ce que le client aura spécifié dans l'entête HTTP Accept:.
- Par exemple, utilisez cet URI de concept pour Douglas Adams – c'est une référence vers la personne du monde réel et non pas vers l'enregistrement physique dans Wikidata :
http://www.wikidata.org/entity/Q42
- En tant qu'être humain pourvu d'yeux et d'un navigateur, vous voudrez accéder aux données concernant Douglas Adams en utilisant l'URI de concept en tant qu'URL. Pour ce faire vous activez une redirection HTTP et envoyez le client sur l'URL de données qui contient les données Wikidata à propos de Douglas Adams : https://www.wikidata.org/wiki/Special:EntityData/Q42.
Lorsque vous avez besoin de contourner la négociation de contenu, par exemple, pour afficher un contenu non HTML dans un navigateur web, vous pouvez spécifier le format des données d'une entité en suffixant l'URL des données avec un suffixe d'extension tel que .json, .rdf, .ttl, .nt ou .jsonld. Par exemple, https://www.wikidata.org/wiki/Special:EntityData/Q42.json vous donne l'élément Q42 dans le format JSON.
Sortie RDF moins verbeuse
Par défaut, les données RDF que l'interface des données liées renvoie sont censées être complètes en elles-mêmes, elles comprennent les descriptions des autres entités auxquelles il fait référence. Si vous voulez exclure ces informations, vous pouvez ajouter le paramètre de requête ?flavor=dump aux URLs demandées.
En ajoutant &flavor à l'URL, vous pouvez contrôler exactement le type de données qui sera renvoyé.
?flavor=dump: Exclue la description des entités auxquellles il est fait référence dans les données.?flavor=simple: Fournit uniquement les déclarations de quasi-vérité (déclarations de meilleur rang sans qualifieurs ni références), en même temps que les liens de site et les informations de version.?flavor=full(default): Un argument full renvoie toutes les données (vous n'avez pas besoin de le spécifier parce que c'est par défaut).
Si vous voulez avoir une idée plus approfondie de ce que chaque option implique exactement, vous pouvez jeter un coup d'œil au code source.
Révisions et mise en cache
Vous pouvez demander des relectures spécifiques d'une entité avec le paramètre de requête revision : https://www.wikidata.org/wiki/Special:EntityData/Q42.json?revision=112.
Les formats d'URL suivants sont utilisés par l'interface utilisateur et par la mise à jour du service de requête respectivement, donc si vous utilisez l'un des mêmes formats d'URL, il y a de fortes chances que vous obteniez des réponses plus rapides (du cache) :
- https://www.wikidata.org/wiki/Special:EntityData/Q42.json?revision=1600533266 (JSON)
- https://www.wikidata.org/wiki/Special:EntityData/Q42.ttl?flavor=dump&revision=1600533266 (RDF sans la description des autres entités)
Service de requêtes Wikidata
Qu'est-ce que c'est ?
Le Wikidata Query Service (WDQS) est le point d'accès SPARQL propre à Wikidata. Il renvoie les résultats des requêtes effectuées à l'aide du langage de requête SPARQL : https://query.wikidata.org
Quand l'utiliser ?
Utiiser WDQS si vous ne connaissez que les caractéristiques des données que vous souhaitez.
N'utilisez pas WDQS pour chercher un texte ou faire une recherche sauvage – FILTER(REGEX(...)) est un anti-motif (utiliser search dans ces cas).
WDQS n'est pas non plus adapté quand les données que vous souhaitez récupérer sont trop nombreuses et représentent un pourcentage substanciel de toutes les données Wikidata; il vaut mieux utiliser un dump dans ce cas.
Détails
Vous pouvez interroger les données de Wikidata à travers notre point d'accès SPARQL, le Wikidata Query Service. Ce service peut s'utiliser aussi bien via l'interface web interactive ou par code en envoyant des requêtes GET ou POST à https://query.wikidata.org/sparql.
La meilleure façon d'utiliser le service de requête est lorsque votre ensemble de résultats correspond exactement à ce que vous cherchez c'est à dire lorsque votre requête cible précisément l'ensemble de vos résultats. Si vous n'avez pas encore une idée bien définie de ce que vous cherchez, alors votre travail en utilisant le service de requête ressemble plus à de la recherche ; ceci est habituellement nécessaire pour affiner votre requête. Voir la section de recherche.
Point d'accès des fragments de données liées
Qu'est-ce que c'est ?
Le point d'accès des fragments de données liées (LDF – Linked Data Fragments) est une méthode plus expérimentale d'accès aux données de Wikidata en spécifiant les motifs avec des triplets : https://query.wikidata.org/bigdata/ldf. Le calcul se fait principalement du côté du client.
Quand l'utiliser ?
Utilisez le point d'accès LDF lorsque vous pouvez définir les données que vous recherchez en utilisant des motifs de triplets, et lorsque votre ensemble de résultats est susceptible d'être assez grand. Le point d'accès est bon à utiliser lorsque vous disposez d'une puissance de calcul importante.
Comme c'est expérimental, n'utilisez pas le point d'accès LDF si vous avez besoin d'un point d'accès absolument stable ou d'un ensemble de résultats rigoureusement complet. Et comme mentionné précédemment, utilisez-le seulement si vous avez suffisamment de puissance de calcul, car le point d'accès LDF décharge le calcul du côté client.
Détails
Si vous disposez d'informations partielles sur ce que vous cherchez comme par exemple deux composants sur trois pour vos triplets, vous pouvez obtenir des résultats en utilisant l'interface des fragments de données liées sur https://query.wikidata.org/bigdata/ldf. Voir le manuel utilisateur et les pages communautaires pour plus d'information.
API REST de Wikibase
Qu'est-ce que c'est ?
L'API REST de Wikibase est une interface basée sur OpenAPI permettant aux utilisateurs d'interagir avec des éléments et des déclarations dans les instances de Wikibase, de les récupérer et de les modifier – y compris bien sûr Wikidata : API REST de Wikidata
Quand l'utiliser ?
L'API REST de Wikibase est encore en développement mais pour Wikidata elle remplace fonctionnellement l'API Action car c'est une interface dédiée créée uniquement pour Wikibase et Wikidata.
Les cas d'utilisation de l'API Action s'appliquent également à l'API REST de Wikibase. Servez-vous en lorsque votre travail implique :
- Modifier Wikidata
- Obtenir les données directes sur les entités elles-mêmes
N'utilisez pas l'API REST de Wikibase quand vos résultats deviennent trop nombreux (envisagez l'utilisation d'un dump dans ces situations).
Il vaut mieux ne pas utiliser l'API REST de Wikibase lorsque vous devez affiner le résultat de votre requête API. Dans ces cas, il vaut mieux réaliser votre travail à l'aide d'un search (sur Elasticsearch) ou d'un query (sur WDQS).
Détails
L'API REST de Wikibase possède une documentation OpenAPI à l'aide de Swagger. Vous pouvez également consulter la documentation développeur.
API Action de MediaWiki
Qu'est-ce que c'est ?
L'API Wikidata est la propre API Action de MediaWiki, étendue avec l'inclusion de certaines actions spécifiques à Wikibase : https://wikidata.org/w/api.php
Quand l'utiliser ?
Utiliser l'API si votre travail concerne :
- Modifier Wikidata
- Obtenir des données sur les entités elles-mêmes, telles que leur historique de révision
- Obtenir toutes les données d'une entité au format JSON, en petits groupes d'entités (jusqu'à 50 entités par requête).
N'utilisez pas l'API lorsque vos résultats deviennent trop nombreux (envisagez plutôt un dump dans ces situations).
L'API est également assez peu adaptée aux situations dans lesquelles vous voulez demander l'état actuel des entités en JSON. Pour ces situations, il vaut mieux utiliser l'interface des données liées, qui de manière équivalente fournit une réponse plus rapidement.
Somme toutes c'est probablement une mauvaise idée que d'utiliser l'API si vous devez affiner le résultat de votre requête API. Dans ce cas, il vaut mieux formater votre travail comme une recherche pour Elasticsearch ou une requête pour WDQS.
Détails
L'API Action de MediaWiki utilisée pour Wikidata est documentée en détails sur la page de l'API de Wikidata. Vous pouvez la parcourir et l'essayer en utilisant le bac à sable de l'API.
Il existe plusieurs points d'accès spécifiques de Wikibase. Voici un exemple de requête :
Robots
Il est également possible d’accéder à l’API en utilisant un robot. Pour en savoir plus sur les robots, voir Wikidata:Bots.
Flux des modifications récentes
Qu'est-ce que c'est ?
Le flux des modifications récentes fournit le flot continu des modifications de tous les wikis Wikimedia y compris Wikidata : https://stream.wikimedia.org.
Quand l'utiliser ?
Utilisez le flux des Modifications récentes lorsque votre projet vous demande de réagir en temps réel aux changements ou lorsque vous avez besoin de toutes les dernières modifications de Wikidata – par exemple, lorsque vous exécutez votre propre service de requête.
Détails
Le flux des modifications récentes contient toutes les mises à jour de tous les wikis qui utilisent le protocole des événements envoyés par les serveurs. Côté client, vous devrez filtrer et séparer les mises à jour de Wikidata.
L'interface web est disponible sur stream.wikimedia.org sa documentation complète se trouve sur la page EventStreams.
Dumps
Qu'est-ce que c'est ?
Les dumps Wikidata sont des exportations complètes de toutes les entités de Wikidata : https://dumps.wikimedia.org
Quand les utiliser ?
Utilisez un dump lorsque votre ensemble de résultats est susceptible d'être très grand. Vous obtiendrez aussi un dump important si vous configurez votre propre service de requête.
N'utilisez pas de dump si vous avez besoin des données actuelles : les dumps prennent très longtemps à s'exporter et encore plus longtemps à se synchroniser avec votre propre service de requête. Les dumps sont également inappropriées lorsque vous avez des limites significatives sur votre bande passante, l'espace de stockage et (ou) la puissance de calcul disponible.
Détails
Si les enregistrements que vous devez traverser sont multiples, ou si l'ensemble de vos résultats est susceptible d'être très grand, il est temps d'envisager de travailler avec un dump de base de données : (lien vers le dernier dump complet).
Vous trouverez la documentation détaillée à propos de tous les dumps Wikimedia sur la page Dumps de données de Meta et concernant les dumps Wikidata en particulier, sur la page téléchargement de la base de données.
Outils
- JsonDumpReader est une bibliothèque PHP pour lire les dumps.
- Vous trouverez sur [1] une bibliothèque Go pour traiter les dumps Wikipedia et Wikidata.
- Vous pouvez utiliser le wdumper pour obtenir des dumps RDF partiels personnalisés.
Service local de requêtes
Fournir un dump de Wikidata n'est pas une tâche très petite ni implémenter les outils ci-dessus pour travailler avec, mais vous pouvez aller un peu plus loin. Si vous avez les possibilités et les ressources pour le faire, vous pouvez héberger votre propre instance du service de requête de Wikidata et l'interroger autant de fois que vous voudrez en dehors de toute contrainte avec les autres.
Pour définir votre propre service de requêtes suivez ces instructions de l'équipe du service des interrogations qui comprend la fourniture de votre propre copie locale des données. Vous trouverez aussi des informations utiles sur l'article dans le billet de blogue de Adam Shorland.