API e modules

API express'Òc - Mòde d'emplec

L'API express'Òc que permet d'afichar expressions en occitan dab la lor traduccion francesa a partir d'un mot-clau.

L'URL d'entrada

L'URL de basa de l'aplicacion qu'ei http://api.locongres.org/expressoc.php. Que i cau ajustar los paramètres obligatòris e que s'i pòt ajustar un paramètre facultatiu. 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 indicar 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 qui voletz trobar dens l'expression o la soa traduccion dab lo paramètre "lang". Qu'accèpta las valors "fr" (tau francés) e "oc" (tà l'occitan).
  • Lo mot a cercar : marcar lo mot qui voletz trobar dens l'expression occitana (o dens la soa traduccion francesa) dab lo paramètre "term".

Per exemple, que's pòt cercar expressions en occitan qui contienen lo mot "boca" dab l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=boca&lang=oc. Qu'avetz lo resultat seguent :

{
    "query": [
        {
            "id": 37,
            "oc": "Aver la boca devath lo nas",
            "var": "gasc",
            "fr": "\u00catre comme tout le monde",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/369",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/nas.jpg",
            "pictureCredit": "David Shankbone",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/bocanas.mp3"
        },
        {
            "id": 220,
            "oc": "Parlar dab la boca ub\u00e8rta ",
            "var": "gasc",
            "fr": "Dire des na\u00efvet\u00e9s",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9705",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/pots.jpg",
            "pictureCredit": "Hamed Saber",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/10Parlardablabocauberta.mp3"
        }
    ]
}

Que podetz tanben cercar expressions dont la traduccion e contien "fuir" dab l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=fuir&lang=fr. Qu'avetz lo resultat seguent :

{
    "query": [
        {
            "id": 86,
            "oc": "Gratar camin",
            "var": "leng",
            "fr": "Aller rapidement, d\u00e9taler, fuir",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/419",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/camin.jpg",
            "pictureCredit": "Manu_H",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/gratarcamin.mp3"
        }
    ]
}

Los paramètres facultatius

La varietat

Que's pòt causir d'afichar expressions sonque en ua varietat de l'occitan en utilizant lo paramètre "var". Peu moment, qu'accèpta las valors "gasc" (tà l'occitan gascon) e "leng" (tà l'occitan lengadocian).

Per exemple, tà afichar totas las expressions en occitan lengadocian qui an lo mot "ivèrn", que podetz utilizar l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=ivèrn&lang=oc&var=leng. Qu'avetz lo resultat seguent :

{
    "query": [
        {
            "id": 230,
            "oc": "Al gr\u00f2s de l\u2019iv\u00e8rn",
            "var": "leng",
            "fr": "Dans le fort de l\u2019hiver",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9715",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/neu.jpg",
            "pictureCredit": "Twice25",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/grosivern.mp3"
        }
    ]
}

Tà afichar ua expression a l'escadut en occitan gascon, que's pòt utilizar l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=random&var=gasc. Qu'avetz quauquarren com :

{
    "query": [
        {
            "id": 128,
            "oc": "Qu'a vist a passar la l\u00e8be",
            "var": "gasc",
            "fr": "Il a eu une d\u00e9convenue",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9558",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/lebe.jpg",
            "pictureCredit": "Fmickan",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/vistpassarlebe.mp3"
        }
    ]
}

La preséncia d'illustracions

Que podetz causir d'afichar sonque las expressions qui son illustradas per un imatge e un son en utilizant lo paramètre "ill" dab la valor "true".

Per exemple, tà afichar totas las expressions illustradas qui an lo mot "talent", que podetz utilizar l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=talent&lang=oc&ill=true. Qu'avetz lo resultat seguent :

{
    "query": [
        {
            "id": 70,
            "oc": "Ai un talent que lo vesi córrer",
            "var": "leng",
            "fr": "J’ai une faim de loup",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/403",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/correr.jpg",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/talentcorrer.mp3"
        }
    ]
}

Afichar ua expression a l'escadut

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

{
    "query": [
        {
            "id": 276,
            "oc": "Destampar l\u2019aiga",
            "var": "leng",
            "fr": "Tirer la chasse",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9761",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/chasseau.jpg",
            "pictureCredit": "Cold Steel",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/destamparaiga.mp3"
        }
    ]
}

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 ua expression a l'escadut au format XML, que's pòt utilizar l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=random&format=xml. Qu'avetz quauquarren com :

<query>
    <expr id="131">
        <oc>Metre un tap a la flaüta</oc>
        <var>leng</var>
        <fr>Se taire, la fermer</fr>
        <url>http://www.locongres.org/fr/applications/expressoc-expressions-fr/expressoc-navigation-par-fiches/9561</url>
        <picture>http://www.locongres.org/images/expressions/flauta.jpg</picture>
        <pictureCredit>Propi</pictureCredit>
        <sound>http://www.locongres.org/images/audio/expressions/tapflauta.mp3</sound>
    </expr>
</query>

Las errors

Si i a errors dens l'URL picada o que la requèsta ne torna pas nada expression, 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 indicar ua clau API
  • 2 : Clau API invalida
  • 3 : Format incorrècte ("json" e "xml" permés)
  • 4 : Que cau indicar un tèrme
  • 5 : Que cau indicar ua lenga de recèrca si n'ètz pas a afichar ua expression a l'escadut
  • 6 : Lenga incorrècta ("fr" e "oc" permés)
  • 7 : Varietat incorrècta ("gasc" e "leng" permés)
  • 8 : N'avem pas trobat nada expression dab las vòstas especificacions
  • 9 : Lo paramètre "ill" qu'accèpta sonque las valors "true" e "false"

Las informacions en sortida

En sortida, qu'avetz ua lista d'expressions dab un identificant unic. Per cadua que son balhats :

  • L'expression en occitan
  • La soa traduccion en francés
  • *L'URL de l'imatge qui illustra l'expression
  • *L'autor qui cau creditar si s'utiliza aqueth imatge
  • *L'URL de l'enregistrament audio de l'expression
  • *L'URL de l'article complet suu site deu Congrès
  • La varietat dens la quau ei l'expression : "gasc" (occitan gascon) o "leng" (occitan lengadocian)

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"
                    },
                    "oc": {
                        "type": "string"
                    },
                    "var": {
                        "type": "string"
                    },
                    "fr": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "picture": {
                        "type": "string"
                    },
                    "pictureCredit": {
                        "type": "string"
                    },
                    "sound": {
                        "type": "string"
                    },
                },
                "required": ["id", "oc", "var", "fr", "url"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (expr) >

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

<! ELEMENT expr (fr | oc | picture? | pictureCredit? | sound? | url | var) >
<! ATTLIST expr id ID #REQUIRED >

<! ELEMENT fr (#PCDATA) >

<! ELEMENT oc (#PCDATA) >

<! ELEMENT picture (#PCDATA) >

<! ELEMENT pictureCredit (#PCDATA) >

<! ELEMENT sound (#PCDATA) >

<! ELEMENT url (#PCDATA) >

<! ELEMENT var (#PCDATA) >

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