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 :

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 :

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 "gascon" (tà l'occitan gascon), "lemosin" (tà l'occitan lemosin), "provenc" (tà l'occitan provençal) e "lengadoc" (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=lengadoc. Qu'avetz lo resultat seguent :

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=gascon. Qu'avetz quauquarren com :

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 :

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 :

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 :

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 ("gascon", "lemosin", "provenc" e "lengadoc" 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 : "oc-gascon" (occitan gascon), "oc-lemosin" (occitan lemosin), "oc-provenc" (occitan provençal) o "oc-lengadoc" (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