Documentation API

Documentation de l'API

Cette page explique le fonctionnement de l'API gratuite de la plateforme Open Data Auvergne Rhône-Alpes.

Authentification

Pour avoir la possibilité d'effectuer un nombre important de requêtes journalières, nous vous conseillons de vous authentifier. En effet, les développeurs non authentifiés ont un quota de requêtes très limité.

Pour vous authentifier, vous devez obtenir une clé d'API et indiquer l'id de l'application pour laquelle vous effectuez votre requête.
Votre clé d'API (Authorization) ainsi que l'id de l'application à l'origine des opérations (Application-ID), doivent ensuite être mentionnés à chaque appel dans les entêtes HTTP.

Pour obtenir votre clé d'API, munissez-vous des identifiants de votre compte développeur sur la plateforme Open Data Auvergne Rhône-Alpes et exéctuez la commande suivante :

$ curl -X POST -d email=(your-e-mail) -d password=(your-password) "http://api.opendata.auvergnerhonealpes.eu/api/1.0/login"

Cela doit retourner une réponse similaire à ceci :


    {"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJleHAiOjE0NTMzNzA0OTYsInVzZXJuYW1lIjoiZmFubnlzY2hhbGxlckBtYWlsLmNvbSIsImlhdCI6IjE0NTMyODQwOTYifQ.AmAgtGsGSS0LCkPDBBZsIkgbY3aFm5obFyffrnH8JvJeX-JHJ4Q6IdO9f_3hgmVckUci70xr3nAkNLUTS0vzyJLnl1weFe2VD-xJWV-Gg8uZ_OmbmAoCXBlNRsKQTZ6lzSU4HMpc9otq5cf8N4wf_rcdTdM9k0NtgXFG7q9QHVmi5Gx6I6w0CUdNYjT33cLHSMlkoKRMaDQlfoK6t19tZNNwjK5-sxkl7Fy-ryabQN2CEIp5FUtN9DQtysERVHs26fLoW6PuNMXHzg1DuGXDiS1dv1A-s6OAAnk8HxQE2SLhjRUuzD54WyquqsLcYuQAixnSYTTZqgANhIoB01SA_MRpMXOPR1ton-C8IM6B4Ei-cJzMhZXYQrtAwye3MmEJTKgYmjF4PmJxlsFSB4E02c1TKewEYnbCu9gPdyP8kSKSg41RDKPzjOjbQFwkcFtRMQWKNF5EXskaeLaG7zNxt8tO_E7L2AhAwqz6aHbBlxyEomkIP353vCzZW904BRvKOev1WNz_gv8gKSNYmq2oWsaH9JTahPK4qoCJHEi6-OkTWgBpk2EZOTD4KqTlWTCzlmvvXiBEdv9njzJEqZJJTyoAjaJdUDNTiIOc59219SOzkKE99rptiwYEPG16AWHVeN1tzatvwv0Xo6-doUPxcrsG5yNWKqPmnZqKS1UhYUE"}

Le token renvoyé constitue votre clé d'API. Cette clé est valable 24h, il vous faudra donc en générer une autre en réexécutant cette commande si vous désirez faire des requêtes authentifiées au-delà de cette limite.

Optimisation des résultats retournés

Les méthodes permettant la récupération d'un ensemble de ressources sont dotées de paramètres vous permettant d'optimiser les résultats :

  • pretty boolean

    Permet d'afficher la réponse JSON en mode lisible

  • q string

    Chaîne de recherche

  • size string, par défaut : 10, maximum : 1000

    Nombre de résultats maximum à retourner
    Ne peut dépasser 1000

  • from string, par défaut : 0

    Index du premier résultat à retourner

  • sort string

    Champ à utiliser pour le tri des résultats
    sort=(field) pour un tri par ordre croissant, sort=-(field) pour un tri par ordre décroissant

Exemples

Voici quelques exemples de requêtes pour mieux comprendre le fonctionnement de notre API. Pour ces exemples, nous utilisons la bibliothèque curl en ligne de commande, mais vous pouvez utiliser d'autres outils similaires de votre choix.

Requête HEAD

Pour commencer, observons les headers retournés par une requête adressée à la page de garde de notre API à l'aide de la commande suivante :

$ curl -i -X HEAD "http://api.opendata.auvergnerhonealpes.eu/api/1.0"

Cela doit retourner une réponse similaire à ceci :


    HTTP/1.1 200 OK
    Server: nginx/1.6.2
    Content-Type: application/json
    Connection: keep-alive
    Cache-Control: no-cache
    Daily-Request-Limit: 200
    Daily-Remaining-Request: 200
    (...)
    Date: Fri, 15 Jan 2016 13:01:36 GMT

On remarquera deux headers intéressants, "Daily-Request-Limit" et "Daily-Remaining-Request". Le premier indique la limite de requêtes journalière fixée dans les paramètres de la plateforme et le second le nombre de requêtes restantes. En effet, vous vous apercevrez si vous lancez une nouvelle fois la commande, que le nombre de requêtes restantes aura diminué.

Parcourir et récupérer des données

Vous pouvez récupérer une liste de ressources (avec ou sans filtres) ou une ressource unique.

Exemple de récupération de l'ensemble des jeux de données contenant le mot "formation" en filtrant par le fournisseur appelé "Fournisseur" :

$ curl -X GET -v "http://api.opendata.auvergnerhonealpes.eu/api/1.0/dataset?pretty=1&q=formation&facet.provider=Fournisseur"


    HTTP/1.1 200 OK
    Server: nginx/1.6.2
    Content-Type: application/json
    Transfer-Encoding: chunked
    Connection: keep-alive
    Cache-Control: no-cache
    Daily-Request-Limit: 200
    Daily-Remaining-Request: 191
    (...)
    Date: Mon, 18 Jan 2016 10:28:30 GMT

    {
        "total": 2,
        "size": 10,
        "from": 0,
        "results": [
            {
                "code": "catalogue-formations",
                "siteCode": [
                    "demo"
                ],
                "title": "Catalogue des formations",
                "provider": "Fournisseur",
                "providerCode": "fournisseur",
                "themes": [],
                "lastUpdatedAt": "2015-12-15T11:22:58+0100",
                "createdAt": "2015-11-20T12:21:46+0100",
                "lastPublishedAt": "2015-12-01T06:53:24+0100",
                "recordsCount": 47,
                "metas": [],
                "fields": [
                    {
                        "name": "formation_dispensee",
                        "type": "string",
                        "title": "Formation dispensée"
                    },
                    {
                        "name": "enseignant",
                        "type": "string",
                        "title": "Enseignant"
                    },
                    {
                        "name": "nombre_de_participants",
                        "type": "numeric",
                        "title": "Nombre de participants"
                    }
                ],
                "dataviz": [
                    {
                        "id": "567902d53a2d2",
                        "title": "Tableau",
                        "pluginCode": "table"
                    }
                ],
                "exports": {
                    "json": "Json",
                    "csv": "CSV",
                    "xlsx": "Microsoft Excel",
                    "xml": "XML",
                    "geojson": "Geojson"
                },
                "downloads": 0,
                "aPrioriNotation": 3,
                "aPosterioriNotation": 3,
                "notation": 3
            },
            {
                ...
            }
        ],
        "facets": {
            "publishedAt": [],
            "tags": [],
            "licence": [],
            "provider": [
                {
                    "key": "Fournisseur",
                    "doc_count": 2
                }
            ],
            "themes": [],
            "language": [],
            "downloads": [
                {
                    "key": 0,
                    "doc_count": 2
                }
            ]
        }
    }

Exemple de récupération du jeu de données dont le code est "annuaire" :

$ curl -X GET -v "http://api.opendata.auvergnerhonealpes.eu/api/1.0/dataset/annuaire?pretty=1"


  HTTP/1.1 200 OK
  Server: nginx/1.6.2
  Content-Type: application/json
  Transfer-Encoding: chunked
  Connection: keep-alive
  Cache-Control: no-cache
  Daily-Request-Limit: 200
  Daily-Remaining-Request: 187
  (...)
  Date: Mon, 18 Jan 2016 12:27:37 GMT

{
    "code": "annuaire",
    "siteCode": [
        "demo"
    ],
    "isEnabled": true,
    "title": "Annuaire",
    "provider": "Fournisseur",
    "providerCode": "fournisseur",
    "themes": [],
    "elementsToBePublished": false,
    "lastUpdatedAt": "2015-11-25T14:42:33+0100",
    "createdAt": "2015-11-25T14:40:26+0100",
    "publishedAt": null,
    "expiredAt": null,
    "lastPublishedAt": "2015-11-25T14:42:33+0100",
    "description": null,
    "tags": null,
    "licenceCode": null,
    "licence": null,
    "languageCode": null,
    "language": null,
    "geographicCoverage": null,
    "coverageFromDate": null,
    "coverageToDate": null,
    "contactName": null,
    "contactMail": null,
    "recordsCount": 22,
    "metas": [],
    "fields": [
        {
            "name": "nom",
            "type": "string",
            "title": "Nom"
        },
        {
            "name": "e-mail",
            "type": "string",
            "title": "E-mail"
        },
        {
            "name": "telephone",
            "type": "string",
            "title": "Téléphone"
        }
    ],
    "dataviz": [],
    "exports": {
        "json": "Json",
        "csv": "CSV",
        "xlsx": "Microsoft Excel",
        "xml": "XML",
        "geojson": "Geojson"
    },
    "downloads": 1,
    "aPrioriNotation": null,
    "aPosterioriNotation": null

}

Consultez la documentation de référence ci-dessous pour avoir plus de précisions sur chaque ressource disponible.