Occitan | Français | English

API et modules

API punt de lenga - Mode d'emploi

Table

# L'URL d'entrée

# Les paramètres obligatoires

# Afficher un article au hasard

# Le format de sortie

# Les erreurs

# Les informations en sortie

# JSON schema

# DTD XML

L'API punt de lenga vous permet de rechercher des articles sur la grammaire occitane à partir d'un mot-clé.

L'URL d'entrée

L'URL de base de l'application est http://api.locongres.org/puntlenga.php. Vous devez y ajouter les paramètres obligatoires. Si vous ne savez pas ajouter des paramètres à un URL, nous vous renvoyons à ce tutoriel.

Les paramètres obligatoires

Il vous faut obligatoirement indiquer les paramètres suivants :

  • Votre clé API : pour utiliser les API du Congrès, il vous faut indiquer une clé API personnelle que nous pouvons vous fournir sur la page dédiée. Vous l'indiquez avec le paramètre "key".
  • La langue : indiquez dans quelle langue vous allez donner le mot-clé avec le paramètre "lang". Il accepte les valeurs "fr" (pour le français) e "oc" (pour l'occitan).
  • Le mot-clé à rechercher : indiquez le mot-clé que vous voulez rechercher dans les articles avec le paramètre "term".

Par exemple, vous pouvez chercher un article dont la version française contient le mot "article" en français avec l'URL http://api.locongres.org/puntlenga.php?key=[votre_clé_API]&term=article&lang=fr&dep=32. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 11,
            "ocTitle": "L'article indefinit",
            "frTitle": "L'article ind\u00e9fini",
            "ocPresentation": "L'article indefinit singular e plural en gascon e en lengadocian.",
            "frPresentation": "L'article ind\u00e9fini singulier et pluriel en gascon et en languedocien.",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9980",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/libe.jpg",
            "cit": "Qu\u2019a escrivut p\u00e8\u00e7as de teatre"
        },
        {
            "id": 12,
            "ocTitle": "L'article partitiu",
            "frTitle": "L'article partitif",
            "ocPresentation": "Ont s'emplega l'article partitiu \u00ab de \u00bb, ont s'exprim\u00eds lo partitiu pel substantiu sol ?",
            "frPresentation": "O\u00f9 emploie-t-on l'article partitif \u00ab de \u00bb, o\u00f9 exprime-t-on le partitif par le substantif seul ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9981",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/versar.jpg",
            "cit": "Balha-li d'aiga"
        },
        {
            "id": 32,
            "ocTitle": "Los noms de montanhas",
            "frTitle": "Les noms de montagnes",
            "ocPresentation": "Quan cau utilizar un article abans un nom de montanha ?",
            "frPresentation": "Quand faut-il utiliser un article avant un nom de montagne ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10001",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/montanha.jpg",
            "cit": "Deis Aups ai Piren\u00e8us"
        },
        {
            "id": 39,
            "ocTitle": "Noms de pa\u00efses e de rius",
            "frTitle": "Noms de pays et de rivi\u00e8res",
            "ocPresentation": "Quand emplegar l'article abans un nom de pa\u00eds o de riu ?",
            "frPresentation": "Quand employer l'article avant un nom de pays ou de rivi\u00e8re ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10008",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/riu.jpg",
            "cit": "Qu\u2019es pres de Tarn"
        }
    ]
}

Vous pouvez rechercher un article dont la version occitane contient le mot "auxiliar" avec l'URL http://api.locongres.org/puntlenga.php?key=[votre_clé_API]&lang=oc&term=auxiliar. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 2,
            "ocTitle": "Causir l\u2019auxiliar \u2013 cases especifics",
            "frTitle": "Choisir l'auxilliaire - cas sp\u00e9cifiques",
            "ocPresentation": "Los cases especific d'emplec dels auxiliars \u00ab \u00e8sser \u00bb e \u00ab aver \u00bb",
            "frPresentation": "Les cas sp\u00e9cifiques d'emploi des auxilliaires \u00ab \u00e8sser \u00bb et \u00ab avoir \u00bb",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9971",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/galerian.jpg",
            "cit": "Qu\u2019av\u00e8van tribalhat com galerians"
        },
        {
            "id": 3,
            "ocTitle": "Causir l\u2019auxiliar \u2013 principis generals",
            "frTitle": "Choisir l'auxilliaire - principes g\u00e9n\u00e9raux",
            "ocPresentation": "Quand emplegar l'auxiliar \u00ab aver \u00bb, quand emplegar l'auxiliar \u00ab \u00e8sser \u00bb ?",
            "frPresentation": "Quand employer l'auxilliaire \u00ab aver \u00bb, quand employer l'auxilliaire \u00ab \u00eatre \u00bb ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9972",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/tribunal.jpg",
            "cit": "L\u2019acusat qu\u2019\u00e8ra estat aquitat"
        },
        {
            "id": 36,
            "ocTitle": "Los v\u00e8rbes semi-auxiliars 1",
            "frTitle": "Les verbes semi-auxilliaires 1",
            "ocPresentation": "Quales son los v\u00e8rbes semi-auxiliars e coma los emplegar ?",
            "frPresentation": "Quels sont les verbes semi-auxilliaires et comment les employer ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10005",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/veitura.jpg",
            "cit": "Ven de crompar una veitura"
        },
        {
            "id": 46,
            "ocTitle": "Los v\u00e8rbes semi-auxiliars 2",
            "frTitle": "Les verbes semi-auxilliaires 2",
            "ocPresentation": "A de qu\u00e9 servisson los v\u00e8rbes semi-auxiliars ?",
            "frPresentation": "\u00c0 quoi servent les verbes semi-auxilliaires ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10015",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/cant.jpg",
            "cit": "Comenc\u00e8t de cantar"
        }
    ]
}

Afficher un article au hasard

Vous pouvez afficher un article au hasard en indiquant la valeur "random" pour le paramètre "term". Dans ce cas-là, vous n'êtes pas obligés d'ajouter la langue. L'URL http://api.locongres.org/puntlenga.php?key=[votre_clé_API]&term=random vous permet donc d'afficher un article au hasard. Vous obtenez quelque chose comme :

{
    "query": [
        {
            "id": 3,
            "ocTitle": "Causir l\u2019auxiliar \u2013 principis generals",
            "frTitle": "Choisir l'auxilliaire - principes g\u00e9n\u00e9raux",
            "ocPresentation": "Quand emplegar l'auxiliar \u00ab aver \u00bb, quand emplegar l'auxiliar \u00ab \u00e8sser \u00bb ?",
            "frPresentation": "Quand employer l'auxilliaire \u00ab aver \u00bb, quand employer l'auxilliaire \u00ab \u00eatre \u00bb ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9972",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/tribunal.jpg",
            "cit": "L\u2019acusat qu\u2019\u00e8ra estat aquitat"
        }
    ]
}

Le format de sortie

Par défaut, le format de sortie est JSON. Mais vous pouvez obtenir une sortie au format XML en ajoutant "format=xml" à l'URL.

Par exemple, si vous voulez afficher un article au hasard au format XML, vous pouvez utiliser l'URL http://api.locongres.org/puntlenga.php?key=[votre_clé_API]&term=random&format=xml. Vous obtenez quelque chose comme :

<query>
    <article id="20">
        <ocTitle>La tonicitat</ocTitle>
        <frTitle>La tonicité</frTitle>
        <ocPresentation>Quaus mots son tonics, atònes proclitics o atònes enclitics ?</ocPresentation>
        <frPresentation>Quels mots sont toniques, atones proclitiques ou atones enclitiques ?</frPresentation>
        <url>http://www.locongres.org/fr/applications/expressoc-expressions-fr/expressoc-navigation-par-fiches/9989</url>
        <picture>http://www.locongres.org/images/expressions/aniversari.jpg</picture>
        <citation>Lo present qu’ei sus la taula</citation>
    </article>
</query>

Les erreurs

S'il y a des erreurs dans l'URL ou si la requête ne retourne aucune forme, l'API retourne une erreur avec un code et un texte d'erreur en anglais. Vous trouverez ci-dessous, pour chaque code d'erreur, la traduction de son texte en français :

  • 1 : Vous devez indiquer une clé API
  • 2 : Clé API invalide
  • 3 : Format incorrect ("json" et "xml" acceptés)
  • 4 : Vous devez indiquer un mot-clé à rechercher
  • 5 : Vous devez indiquer une langue de recherche si vous n'êtes pas en train d'afficher un article au hasard
  • 6 : Langue incorrecte ("fr" et "oc" acceptés)
  • 7 : Nous n'avons trouvé aucun article avec vos spécifications

Les informations en sortie

En sortie, vous obtenez une liste d'articles avec un identifiant unique. Pour chacun est donné :

  • Son titre en occitan
  • Son titre en français
  • Sa présentation en occitan
  • Sa présentation en francés
  • L'URL de l'article complet sur le site du Congrès
  • La citation qui illustre l'article
  • L'URL de l'image qui illustre la citation
  • *L'auteur qu'il faut créditer si on utilise cette image

Les champs précédés de * n'apparaissent pas obligatoirement.

JSON schema

{
    "type": "object",
    "properties": {
        "error": {
            "type": "object",
            "properties": {
                "code": {
                    "description": "The unique identifier for an error",
                    "type": "integer"
                },
                "text": {
                    "description": "A description of the error",
                    "type": "string"
                }
            },
            "required": ["code", "text"]
        },
        "query": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "ocTitle": {
                        "type": "string"
                    },
                    "frTitle": {
                        "type": "string"
                    },
                    "ocPresentation": {
                        "type": "string"
                    },
                    "frPresentation": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "picture": {
                        "type": "string"
                    },
                    "pictureCredit": {
                        "type": "string"
                    },
                    "cit": {
                        "type": "string"
                    },
                },
                "required": ["id", "ocTitle", "frTitle", "ocPresentation", "frPresentation", "url", "picture", "cit"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (article) >

<! ELEMENT error (#PCDATA) >
<! ATTLIST error code ID #REQUIRED >

<! ELEMENT article (citation, frPresentation, frTitle, ocPresentation, ocTitle, picture, pictureCredit?, url) >
<! ATTLIST article id ID #REQUIRED >

<! ELEMENT citation (#PCDATA) >

<! ELEMENT frPresentation (#PCDATA) >

<! ELEMENT frTitle (#PCDATA) >

<! ELEMENT ocPresentation (#PCDATA) >

<! ELEMENT ocTitle (#PCDATA) >

<! ELEMENT picture (#PCDATA) >

<! ELEMENT pictureCredit (#PCDATA) >

<! ELEMENT url (#PCDATA) >

Hauteur

© Lo Congrès Permanent de la Lenga Occitana, 2017, tous droits réservés - Contacter Lo Congrès