L'API top'Òc que permet de tradúser un toponime deu francés a l'occitan e vice-versa e d'aver los noms occitan e francés d'ua comuna a partir deu son còdi o de las soas coordenadas.

L'URL d'entrada

L'URL de basa de l'aplicacion qu'ei http://api.locongres.org/topoc.php. Que 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 : tà ua recèrca per nom, marcar en quau lenga anatz balhar lo nom deu toponime dab lo paramètre "lang". Qu'accèpta las valors "fr" (tau francés) e "oc" (tà l'occitan).
• Lo nom deu toponime o lo còdi comuna o la latitud e la longitud** : marcar sia lo nom deu toponime dont voletz obtiéner la traduccion dab lo paramètre "name", sia lo còdi comuna dab lo paramètre "code", sia la latitud e la longitud dab los paramètres "lat" e "long".
• Lo departament o lo tipe (per las recèrcas per nom sonque) : tà cercar ua comuna deu territòri francés, marcar lo son departament dab duas chifras en valor deu paramètre "dep"*. Sinon, marcar lo tipe de toponime internacionau recercat dab lo paramètre "type" qui pòt aver com valor "city" (vilas deu monde) o "country" (país deu monde).

* Peu moment, lo top'Òc qu'intègra las comunas deus departaments seguents : 09, 12, 31, 32, 33, 40, 46, 47, 64, 65, 81 e 82.

** Cercar per còdi comuna o per coordenadas que's pòt sonque per las comunas deu territòri francés.

Per exemple, que's pòt cercar lo nom en occitan de la comuna deu Gèrs qui s'apèra "Auch" en francés dab l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=Auch&lang=fr&dep=32. Qu'avetz lo resultat seguent :

Que's pòt cercar la traduccion en francés deu nom de país "Bolívia" dab l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=bolívia&lang=oc&type=country. Qu'avetz lo resultat seguent :

Que's pòt cercar los noms en francés e en occitan de la comuna qui a com còdi "64001" dab l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&code=64001. Qu'avetz lo resultat seguent :

Que's pòt cercar los noms en francés e en occitan de la comuna mei pròcha de las coordenadas 43.4662 de latitud e 1.35 de longitud dab l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&lat=43.4662&long=1.35. Qu'avetz lo resultat seguent :

Los paramètres facultatius

Las illustracions

Que podetz causir d'afichar sonque los toponimes qui son illustrats per un imatge e ua anecdòta en utilizant lo paramètre "ill" dab la valor "true".

Per exemple, tà afichar a l'azard ua ciutat illustrada de Tarn, que podetz utilizar l'URL https://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&dep=81&ill=true. Qu'avetz lo resultat seguent :

La varietat

Las petitas anecdòtas que son redigidas dens mei d'ua varietat de l'occitan. Que podetz causir d'afichar sonque los toponimes qui an l'anecdòta dens ua varietat especifica dab lo paramètre "var". Peu moment, qu'accèpta las valors "gascon" (tà l'occitan gascon) e "lengadoc" (tà l'occitan lengadocian).

Per exemple, tà afichar a l'azard ua ciutat illustrada qui a l'anecdòta en occitan gascon, que podetz utilizar l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&ill=true&var=gascon. Qu'avetz lo resultat seguent :

Afichar un toponime a l'escadut

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

Tà causir a l'escadut un toponime d'un departament precís o d'un tipe particular, ajustar lo paramètre "dep" o lo paramètre "type". Per exemple, tà afichar a l'escadut ua comuna d'Òut, utilizar l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&dep=46. 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, si voletz afichar lo toponime "Bratislava" au format XML, que podetz utilizar l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=Bratislava&lang=fr&type=city&format=xml. Qu'avetz lo resultat seguent :

Las errors

Si i a errors dens l'URL qui avetz picada o que la requèsta ne torna pas nat toponime, 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 sia un nom de toponime, sia un còdi comuna, sia ua latitud e ua longitud
• 5 : Que cau indicar ua lenga de recèrca si n'ètz pas a afichar un toponime a l'escadut o a cercar per còdi comuna o per coordenadas
• 6 : Lenga incorrècta ("fr" e "oc" permés)
• 7 : Departament incorrècte ("09", "12", "31", "32", "33", "40", "46", "47", "64", "65", "81" e "82" permés)
• 8 : Tipe incorrècte ("city" e "country" permés)
• 9 : Que cau indicar un tipe o un departament si n'ètz pas a afichar un toponime a l'escadut o a cercar per còdi comuna o per coordenadas
• 10 : N'avem pas trobat nat toponime dab las vòstas especificacions
• 11 : Lo paramètre "ill" qu'accèpta sonque las valors "true" e "false"
• 12 : Varietat incorrècta ("lengadoc" e "gascon" permés)

Las informacions en sortida

En sortida, qu'avetz ua lista de toponimes dab un identificant unic. Per cadun que son balhats :

• Lo son nom en occitan
• Lo son nom en francés
• *Lo departament : dab duas chifras
• *Lo tipe : "city" (vila deu monde) o "country" (país deu monde)
• *La soa latitud
• *La soa longitud
• *Lo son còdi comuna
• *L'URL de l'imatge qui illustra lo toponime
• *L'autor qui cau creditar si s'utiliza aqueth imatge
• *Ua anecdòta en occitan sus la ciutat
• *La revirada en francés de l'anecdòta sus la ciutat
• *L'URL de la pagina del toponime sus la Wikipèdia occitana
• *La varietat de l'anecdòta

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

La latitud, la longitud e lo còdi comuna qu'apareishen sonque tà las comunas deu territòri francés.

L'imatge, los crèdits, l'anecdòta e sa revirada, la pagina Wikipèdia e la varietat qu'apareishen sonque tà las comunas illustradas.

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"
                    },
                    "fr": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string"
                    },
                    "dep": {
                        "type": "string"
                    },
                    "lat": {
                        "type": "string"
                    },
                    "long": {
                        "type": "string"
                    },
                    "cityCode": {
                        "type": "string"
                    },
                    "picture": {
                        "type": "string"
                    },
                    "pictureCredit": {
                        "type": "string"
                    },
                    "anecdoteOc": {
                        "type": "string"
                    },
                    "anecdotefr": {
                        "type": "string"
                    },
                    "wikipedia": {
                        "type": "string"
                    },
                    "variety": {
                        "type": "string"
                    },
                },
                "required": ["id", "oc", "fr"]
            },
            "minItems": 1
        }
    }
}

DTD XML