L'API top'Òc vous permet de traduire un toponyme du français à l'occitan et inversement et d'obtenir les noms occitan et français d'une commune à partir de son code ou ses coordonnées.

L'URL d'entrée

L'URL de base de l'application est http://api.locongres.org/topoc.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 : si vous cherchez par nom, indiquez dans quelle langue vous allez donner le nom du toponyme avec le paramètre "lang". Il accepte les valeurs "fr" (pour le français) e "oc" (pour l'occitan).
• Le nom du toponyme ou le code commune ou la latitude et la longitude** : indiquez soit le nom du toponyme dont vous voulez obtenir la traduction avec le paramètre "name", soit le code commune avec le paramètre "code", soit la latitude et la longitude avec les paramètres "lat" et "long".
• Le département ou le type (pour les recherches par nom uniquement) : si vous cherchez une commune du territoire français, indiquez son département avec deux chiffres en valeur du paramètre "dep"*. Sinon, indiquez le type de toponyme international recherché avec le paramètre "type" qui peut prendre en valeur "city" (villes du monde) o "country" (pays du monde).

* Pour le moment, le top'Òc intègre les communes des départements suivants : 09, 12, 31, 32, 33, 40, 46, 47, 64, 65, 81 et 82.

** La recherche par code commune ou par coordonnées est disponible uniquement pour les villes du territoire français.

Par exemple, vous pouvez chercher le nom en occitan de la commune du Gers qui s'appelle "Auch" en français avec l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&name=Auch&lang=fr&dep=32. Vous obtenez le résultat suivant :

Vous pouvez chercher quelle est la traduction en français du nom de pays "Bolívia" avec l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&name=bolívia&lang=oc&type=country. Vous obtenez le résultat suivant :

Vous pouvez chercher les noms en français et en occitan de la commune qui a pour code "64001" avec l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&code=64001. Vous obtenez le résultat suivant :

Vous pouvez chercher les noms en français et en occitan de la commune la plus proche des coordonnées 43.4662 de latitude et 1.35 de longitude avec l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&lat=43.4662&long=1.35. Vous obtenez le résultat suivant :

Les paramètres facultatifs

Les illustrations

Vous pouvez choisir d'afficher uniquement les toponymes qui sont illustrés par une image et une anecdote en utilisant le paramètre "ill" avec la valeur "true".

Par exemple, pour afficher au hasard une commune illustrée du Tarn, vous pouvez utiliser l'URL https://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&dep=81&ill=true. Vous obtiendrez le résultat suivant :

La variété

Les petites anecdotes sont rédigées dans plusieurs variétés de l'occitan. Vous pouvez choisir d'afficher seulement les toponymes dont l'anecdote est dans une variété spécifique avec le paramètre "var". Pour le moment, il accepte les valeurs "gascon" (pour l'occitan gascon) e "lengadoc" (pour l'occitan languedocien).

Par exemple, pour afficher au hasard une ville illustrée dont l'anecdote est en occitan gascon, vous pouvez utiliser l'URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&ill=true&var=gascon. Vous obtiendrez le résultat suivant :

Afficher un toponyme au hasard

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

Si vous voulez choisir au hasard un toponyme d'un département précis ou d'un type particulier, ajoutez le paramètre "dep" ou le paramètre "type". Par exemple, pour afficher au hasard une commune du Lot, utilisez l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&name=random&dep=46. Vous obtenez quelque chose comme :

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 le toponyme "Bratislava" au format XML, vous pouvez utiliser l'URL http://api.locongres.org/topoc.php?key=[votre_clé_API]&name=Bratislava&lang=fr&type=city&format=xml. Vous obtenez le résultat suivant :

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 soit un nom de toponyme, soit un code commune, soit une latitude et une longitude
• 5 : Vous devez indiquer une langue de recherche si vous n'êtes pas en train d'afficher un toponyme au hasard ou que vous ne cherchez pas par code commune ou par coordonnée
• 6 : Langue incorrecte ("fr" et "oc" acceptés)
• 7 : Département incorrect ("09", "12", "31", "32", "33", "40", "46", "47", "64", "65", "81" et "82" acceptés)
• 8 : Type incorrect ("city" et "country" acceptés)
• 9 : Il vous faut indiquer un type ou un département si vous n'êtes pas en train d'afficher un toponyme au hasard ou que vous ne cherchez pas par code commune ou par coordonnée
• 10 : Nous n'avons trouvé aucun toponyme avec vos spécifications
• 11 : Le paramètre "ill" n'accepte que les valeurs "true" et "false"
• 12 : Variété incorrecte ("lengadoc" et "gascon" acceptés)

Les informations en sortie

En sortie, vous obtenez une liste de toponymes avec un identifiant unique. Pour chacun sont donnés :

• Son nom en occitan
• Son nom en français
• *Le département : sur deux chiffres
• *Le type : "city" (ville du monde) o "country" (pays du monde)
• *Sa latitude
• *Sa longitude
• *Son code commune
• *L'URL de l'image qui illustre le toponyme
• *L'auteur qu'il faut créditer si on utilise cette image
• *Une anecdote en occitan sur la ville
• *La traduction en français de l'anecdote sur la ville
• *L'URL de la page du toponyme sur la Wikipédia occitane
• *La variété de l'anecdote

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

La latitude, la longitude et le code commune n'apparaissent que pour les communes du territoire français.

L'image, les crédits, l'anecdote et sa traduction, la page Wikipédia et la variété n'apparaissent que pour les communes illustrées.

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