API e modules

API punt de lenga - Mòde d'emplec

L'API punt de lenga que permet de recercar articles sus la gramatica occitana a partir d'un mot-clau.

L'URL d'entrada

L'URL de basa de l'aplicacion qu'ei http://api.locongres.org/puntlenga.php. Que i cau ajustar los paramètres obligatòris. Si ne sabetz pas ajustar paramètres a un URL, que'vs renviam a aqueth tutoriau.

Los paramètres obligatòris

Que cau obligatòriament marcar los paramètres seguents :

  • La vòsta clau API : tà utilizar las API deu Congrès, que cau marcar ua clau API personau qui'vs podem balhar sus la pagina dedicada. Que la cau marcar dab lo paramètre "key".
  • La lenga : marcar en quau lenga anatz balhar lo mot clau dab lo paramètre "lang". Qu'accèpta las valors "fr" (tau francés) e "oc" (tà l'occitan).
  • Lo mot clau de cercar : marcar lo mot-clau qui voletz recercar dens los articles dab lo paramètre "term".

Per exemple, que's pòt cercar un article dont la version francesa e contien lo mot "article" en francés dab l'URL http://api.locongres.org/puntlenga.php?key=[la_vòsta_clau_API]&term=article&lang=fr. Qu'avetz lo resultat seguent :

{
    "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"
        }
    ]
}

que's pòt cercar un article dont la version occitana e contien lo mot "auxiliar" dab l'URL http://api.locongres.org/puntlenga.php?key=[la_vòsta_clau_API]&lang=oc&term=auxiliar. Qu'avetz lo resultat seguent :

{
    "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"
        }
    ]
}

Afichar un article a l'escadut

que's pòt afichar un article a l'escadut en indicant la valor "random" tau paramètre "term". En aqueth cas, n'i a pas cap d'obligacion d'ajustar la lenga. L'URL http://api.locongres.org/puntlenga.php?key=[la_vòsta_clau_API]&term=random que permet doncas d'afichar un article a l'escadut. Qu'avetz quauquarren com :

{
    "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"
        }
    ]
}

Lo format de sortida

Per defaut, lo format de sortida qu'ei JSON. Mes que's pòt aver ua sortida au format XML en ajustant "format=xml" a l'URL.

Per exemple, tà afichar un article a l'escadut au format XML, que's pòt utilizar l'URL http://api.locongres.org/puntlenga.php?key=[la_vòsta_clau_API]&term=random&format=xml. Qu'avetz quauquarren com :

<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>

Las errors

Si i a errors dens l'URL picada o que la requèsta ne torna pas nat article, l'API que torna ua error dab un còdi e un tèxte d'error en anglés. Qu'avetz ací-devath, tà cada còdi d'error, la revirada deu son tèxte en occitan :

  • 1 : Que cau marcar ua clau API
  • 2 : Clau API invalida
  • 3 : Format incorrècte ("json" e "xml" permés)
  • 4 : Que cau marcar un mot-clau a cercar
  • 5 : Que cau marcar ua lenga de recèrca si n'ètz pas a afichar un article a l'escadut
  • 6 : Lenga incorrècta ("fr" e "oc" permés)
  • 7 : N'avem pas trobat nat article dab las vòstas especificacions

Las informacions en sortida

En sortida, qu'avetz ua lista d'articles dab un identificant unic. Per cadun qu'ei balhat :

  • Lo son títol en occitan
  • Lo son títol en francés
  • La soa presentacion en occitan
  • La soa presentacion en francés
  • L'URL de l'article complet suu site deu Congrès
  • La citacion qui illustra l'article
  • L'URL de l'imatge qui illustra la citacion
  • *L'autor qui cau creditar si s'utiliza aqueth imatge

Los camps davantejats de * n'apareishen pas a cada còp.

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) >

© Lo Congrès Permanent de la Lenga Occitana, 2017, tots los drets reservats - Contactar Lo Congrès