API SPARQL : interrogez vos graphes de connaissances avec SPARQL

01

📖 Qu'est-ce que l'API SPARQL ?

L'API SPARQL est un endpoint REST qui permet d'interroger un graphe de connaissances via le langage SPARQL, standard du web sémantique. Elle expose un point d'accès unique pour exécuter des requêtes SELECT, CONSTRUCT, ASK et DESCRIBE.

💡 À retenir : SPARQL est au web sémantique ce que SQL est aux bases relationnelles. L'API SPARQL est l'équivalent d'un serveur SQL pour vos graphes RDF.

🌐 Endpoint public :
https://lemondesemantique.fr/api/sparql

Caractéristiques :

✅ Support des requêtes SELECT, CONSTRUCT, ASK, DESCRIBE
✅ Authentification par clé API
✅ Résultats en JSON, XML, CSV, TSV, RDF/XML, Turtle
✅ Rate limiting pour protéger le service
✅ Timeout configurable pour les requêtes complexes

02

🔌 SPARQL Endpoint

Le SPARQL Endpoint accepte les requêtes via GET et POST.

Requête GET

curl "https://lemondesemantique.fr/api/sparql?query=SELECT+*+WHERE{?s+?p+?o}+LIMIT+10&format=json" \
  -H "X-API-Key: votre_clé_api"

Requête POST (recommandée)

curl -X POST https://lemondesemantique.fr/api/sparql \
  -H "X-API-Key: votre_clé_api" \
  -H "Content-Type: application/sparql-query" \
  -d "SELECT * WHERE { ?s ?p ?o } LIMIT 10"

Paramètres disponibles

Paramètre	Description	Exemple
query	La requête SPARQL (URL encodée en GET)	SELECT * WHERE { ?s ?p ?o }
format	Format de réponse	json, xml, csv, ttl, rdfxml
limit	Nombre maximum de résultats	100 (défaut), 1000 max
timeout	Temps maximum d'exécution (secondes)	30 (défaut), 120 max

03

📊 Types de requêtes SPARQL

SELECT - Extraire des données

PREFIX schema: 
PREFIX foaf: 

SELECT ?nom ?dateNaissance
WHERE {
  ?orateur a foaf:Person ;
           foaf:name ?nom ;
           schema:birthDate ?dateNaissance .
}
ORDER BY ?dateNaissance
LIMIT 20

CONSTRUCT - Créer un nouveau graphe

PREFIX schema: 

CONSTRUCT {
  ?orateur schema:name ?nom .
}
WHERE {
  ?orateur a schema:Person ;
           schema:name ?nom .
}

ASK - Tester l'existence

ASK {
  ?discours schema:author  .
}

DESCRIBE - Décrire une ressource

DESCRIBE

04

🎯 Exemples concrets

1. Tous les orateurs

curl -X POST https://lemondesemantique.fr/api/sparql \
  -H "X-API-Key: votre_clé" \
  -H "Content-Type: application/sparql-query" \
  -d "PREFIX foaf: 
      SELECT ?nom WHERE {
        ?orateur a foaf:Person ;
                 foaf:name ?nom .
      } ORDER BY ?nom"

2. Discours d'un orateur spécifique

curl -X POST https://lemondesemantique.fr/api/sparql \
  -H "X-API-Key: votre_clé" \
  -H "Content-Type: application/sparql-query" \
  -d "PREFIX schema: 
      SELECT ?titre ?date WHERE {
        
            schema:author ?discours .
        ?discours schema:title ?titre ;
                  schema:date ?date .
      } ORDER BY ?date"

3. Recherche par mot-clé dans les discours

curl -X POST https://lemondesemantique.fr/api/sparql \
  -H "X-API-Key: votre_clé" \
  -H "Content-Type: application/sparql-query" \
  -d "PREFIX schema: 
      SELECT ?titre ?contenu WHERE {
        ?discours schema:title ?titre ;
                  schema:content ?contenu .
        FILTER(CONTAINS(?contenu, 'résistance'))
      }"

4. Graphe de connaissances (2 sauts)

curl -X POST https://lemondesemantique.fr/api/sparql \
  -H "X-API-Key: votre_clé" \
  -H "Content-Type: application/sparql-query" \
  -d "PREFIX ex: 
      SELECT ?orateur1 ?orateur2 ?discoursCommun WHERE {
        ?orateur1 ex:aPrononce ?discoursCommun .
        ?orateur2 ex:aPrononce ?discoursCommun .
        FILTER(?orateur1 != ?orateur2)
      } LIMIT 10"

📝 Réponse JSON :

{
  "head": { "vars": ["nom", "dateNaissance"] },
  "results": {
    "bindings": [
      { "nom": { "value": "Victor Hugo" }, "dateNaissance": { "value": "1802-02-26" } },
      { "nom": { "value": "Charles de Gaulle" }, "dateNaissance": { "value": "1890-11-22" } }
    ]
  }
}

05

📄 Formats de réponse

L'API SPARQL supporte plusieurs formats via le paramètre format ou le header Accept.

Format	Paramètre format	Accept Header
JSON	`json`	`application/json`
XML	`xml`	`application/xml`
CSV	`csv`	`text/csv`
TSV	`tsv`	`text/tab-separated-values`
Turtle (RDF)	`ttl`	`text/turtle`
RDF/XML	`rdfxml`	`application/rdf+xml`

💡 Astuce : Pour les requêtes CONSTRUCT, privilégiez les formats RDF (Turtle, RDF/XML). Pour SELECT, utilisez JSON ou CSV.

06

🔗 Intégration dans vos applications

Python avec SPARQLWrapper

from SPARQLWrapper import SPARQLWrapper, JSON

sparql = SPARQLWrapper("https://lemondesemantique.fr/api/sparql")
sparql.setCredentials("", "votre_clé_api", "X-API-Key")
sparql.setQuery("""
    PREFIX foaf: 
    SELECT ?nom WHERE {
        ?orateur a foaf:Person ;
                 foaf:name ?nom .
    } LIMIT 10
""")
sparql.setReturnFormat(JSON)
results = sparql.query().convert()

for result in results["results"]["bindings"]:
    print(result["nom"]["value"])

JavaScript / Node.js

const query = `
  PREFIX foaf: 
  SELECT ?nom WHERE {
    ?orateur a foaf:Person ;
             foaf:name ?nom .
  } LIMIT 10
`;

fetch('https://lemondesemantique.fr/api/sparql', {
  method: 'POST',
  headers: {
    'X-API-Key': 'votre_clé_api',
    'Content-Type': 'application/sparql-query'
  },
  body: query
})
.then(response => response.json())
.then(data => console.log(data));

PHP

$ch = curl_init('https://lemondesemantique.fr/api/sparql');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: votre_clé_api',
    'Content-Type: application/sparql-query'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
$response = curl_exec($ch);
$data = json_decode($response, true);

07

⚠️ Bonnes pratiques et limites

Bonnes pratiques

✅ Utilisez POST pour les requêtes longues
✅ Spécifiez LIMIT pour éviter des résultats trop volumineux
✅ Utilisez des PREFIX pour améliorer la lisibilité
✅ Préférez DESCRIBE à SELECT * pour explorer une ressource
✅ Testez vos requêtes sur l'interface web avant intégration

Limites techniques

Limite	Valeur
Timeout maximum	120 secondes
LIMIT maximum	10 000 résultats
Taille requête	10 MB
Requêtes par minute (gratuit)	60
Requêtes par minute (pro)	600

⚠️ Attention : Les requêtes non optimisées sur de grands graphes peuvent être lentes. Utilisez des filtres et des limites pour améliorer les performances.

08

API SPARQL