OpenDataSoft - API supportees

API de la plateforme OpenDataSoft (ODS), utilisee par de nombreux portails open data publics (data.economie.gouv.fr, data.education.gouv.fr, etc.). C'est l'API la plus complete en termes de capacites serveur.

API la plus riche

OpenDataSoft supporte toutes les fonctionnalites serveur : pagination, facettes, recherche full-text, group-by, tri et agrégation. Les requêtes utilisent la syntaxe ODSQL, un dialecte SQL simplifie.

Capacites serveur

Capacite	Support	Détail
Fetch serveur	Oui	Recuperation paginee des données
Facettes serveur	Oui	Endpoint dedie `/facets`
Recherche serveur	Oui	Full-text via `search("{q}")`
Group-by serveur	Oui	Clause `group_by` ODSQL
Tri serveur	Oui	Clause `order_by` ODSQL
Agrégation serveur	Oui	Fonctions `sum`, `avg`, `count`, `min`, `max` dans `select`

Pagination

Paramètre	Valeur
Type	`offset`
Taille de page	100 enregistrements
Pages max	10
Enregistrements max	1 000
Paramètres URL	`offset`, `limit`

La limite de 1 000 enregistrements s'applique a la recuperation client-side via dsfr-data-source. Pour les agrégations et group-by, utilisez dsfr-data-query qui delegue le calcul au serveur ODS.

Syntaxe de requête (ODSQL)

OpenDataSoft utilise ODSQL, un dialecte SQL simplifie, pour les clauses select, where, group_by et order_by.

Exemples de syntaxe

Clause	Exemple
`select`	`region, sum(population) as population__sum`
`where`	`departement = "75" AND population > 1000`
`group_by`	`region`
`order_by`	`population__sum DESC`

Separateur WHERE

Les clauses WHERE multiples sont jointes par AND .

Chercher du texte : `like` compare des mots

Le like d'ODSQL n'est pas une recherche de sous-chaîne, et le % n'y est pas un joker : il compare des mots. Mesuré le 2026-10-12 sur rappelconso-v2-gtin-trie (data.economie.gouv.fr, 18 559 lignes) et le 2026-10-13 sur data.education.gouv.fr :

Clause	Lignes	Lecture
`categorie_produit like "%aliment%"`	0	mot entier « aliment » : aucun — 14 366 lignes valent pourtant « alimentation »
`categorie_produit like "alimentation"`	14 366	mot entier
`categorie_produit like "alim*"`	15 632	début de mot (« alimentation », « hors alimentaire »)
`categorie_produit like "*tation"`	0	pas de recherche par fin ou milieu de mot
`categorie_produit like "ALIMENT"`, `"bebes*"`	15 632, 1 266	casse et accents ignorés

La bibliothèque en tire une conséquence : les opérateurs contains et notcontains (une sous-chaîne) n'ont aucun équivalent ODSQL. Ils ne sont jamais confiés à un portail OpenDataSoft : ils sont calculés dans le navigateur, sur les lignes que les autres clauses du filtre ont laissées passer. La source charge donc ces lignes-là, dans la limite de max-records, et ce calcul n'est pas compatible avec server-side ni avec server-facets (erreur de configuration). Le where écrit en ODSQL sur la source, lui, part tel quel : un like y garde la sémantique du portail. Pour une recherche saisie par le visiteur, dsfr-data-search utilise la recherche du portail, par début de mot, casse et accents ignorés : search("…") dans tous les champs en server-search, search(champ, "…") dans le champ nommé en mode context (mesuré le 2026-10-13 sur le même jeu : search("aliment") rend 15 866 lignes, search(categorie_produit, "aliment") 15 636, et search(sous_categorie_produit, "iand"), un milieu de mot, aucune ; un champ qui n'est pas du texte fait répondre HTTP 400). Cette recherche-là entre dans le where de la source : elle est compatible avec server-side et server-facets. Voir dsfr-data-query, « contains est une sous-chaîne ».

Facettes

Paramètre	Valeur
Mode par défaut	server
Endpoint	`/facets` (dedie)

Les facettes sont calculees cote serveur, ce qui est tres performant même sur de gros jeux de données. Utilisez <dsfr-data-facets server-facets> pour activer ce mode.

Authentification

Type : API key en header (apikey-header).
La plupart des portails ODS publics ne necessitent pas d'authentification. Pour les datasets prives, ajoutez la clé API via le header Authorization.

Structure de reponse

Paramètre	Valeur
Chemin des données	`results`
Chemin du total	`total_count`
Données imbriquees	Non (champs a plat)
Necessite flatten	Non

Detection automatique

dsfr-data détecté automatiquement une source OpenDataSoft si l'URL contient :

/api/explore/v2.1/catalog/datasets/{datasetId}

Portails connus : data.economie.gouv.fr, data.education.gouv.fr, et tout domaine *.opendatasoft.com.

Exemple d'utilisation

Graphique simple

<dsfr-data-source
  id="src"
  api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr"
  dataset-id="mon-dataset">
</dsfr-data-source>

<dsfr-data-query
  id="stats"
  source="src"
  group-by="region"
  aggregate="valeur:sum">
</dsfr-data-query>

<dsfr-data-chart
  source="stats"
  type="bar"
  label-field="region"
  value-field="valeur__sum">
</dsfr-data-chart>

Avec facettes serveur

<dsfr-data-source
  id="src"
  api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr"
  dataset-id="mon-dataset"
  server-side>
</dsfr-data-source>

<dsfr-data-facets
  source="src"
  fields="region,departement"
  server-facets>
</dsfr-data-facets>