The top'Òc API allows you to translate a toponym from french to occitan and vice-versa and to get a city french and occitan names from its code or its coordinates.

Input URL

The application basic URL is http://api.locongres.org/topoc.php. You have to add mandatory parameters. If you don't know how to add parameters in an URL, you can read this tutorial.

Mandatory parameters

You have to add the following parameters :

• Your API key : to use Lo Congrès API, you have to specify a personal API key you can get on the dedicate page. You specify the API key with the "key" parameter.
• Language : if you're searching by name, you have to specify in which language you will give the toponym name with the "lang" parameter. It allows the values "fr" (for french) and "oc" (for occitan).
• Toponym name or city code or latitude and longitude** : you have to specify either the name of the toponym you want to get the translation with the "name" parameter, or the city code with the "code" parameter, or a latitude and a longitude with the "lat" and "long" parameters.
• Department or type (for searching by name only) : if you search a city in french territory, you have to indicate its department with two numbers as value of the "dep" parameter*. Otherwise, you have to indicate the type of international toponym you ask for with the "type" parameter which allows the values "city" (world cities) or "country" (world countries).

* For the moment, you can find in the top'Òc cities of the following french departments : 09, 12, 31, 32, 33, 40, 46, 47, 64, 65, 81 and 82.

** Searching by city code or by coordinates is only possible for french territory cities.

For instance, you can search the occitan name of the Gers city whose french name is "Auch" with the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&name=Auch&lang=fr&dep=32. You get the following result :

You can search the french translation of the occitan country name "Bolívia" with the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&name=bolívia&lang=oc&type=country. You get the following result :

You can search the french and occitan names of the city whose code is "64001" with the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&code=64001. You get the following result :

You can search the french and occitan names of the city closest to the coordinates 43.4662 latitude and 1.35 longitude with the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&lat=43.4662&long=1.35. You get the following result :

Facultative parameters

Illustrations

You can choose to display only toponyms that are illustrated by a picture and a fun fact using the "ill" parameter with the value "true".

For instance, to display all the illustrated cities of Tarn, you can use the URL https://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&dep=81&ill=true. You get the following result :

Variety

The little fun facts are redacted in many occitan varieties. You can choose to display only the toponyms whose fun fact is in a specific variety with the "var" parameter. For the moment, it allows the values "gascon" (for Gascony occitan) e "lengadoc" (for Languedoc occitan).

For uinstance, to display randomly an illustrated city whose fun fact is in Gascony occitan, you can use the URL http://api.locongres.org/topoc.php?key=[la_vòsta_clau_API]&name=random&ill=true&var=gascon. You get the following result :

Display randomly a toponym

You can display randomly a toponym in specifying the value "random" for the parameter "name". In that case, you don't have to specify a language and a type or a department. So the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&name=random allows you to display randomly a toponym. You get the something like this :

If you want to display randomly a toponym from a precise department or particular type, add the parameter "dep" or the parameter "type". For instance, to display randomly a Lot city, use the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&name=random&dep=46. You get the something like this :

Output format

The default output format is JSON. But you can get an XML output in adding "format=xml" to the l'URL.

For instance, if you want to display the toponym "Bratislava" in XML format, you can use the URL http://api.locongres.org/topoc.php?key=[your_APIkey]&name=Bratislava&lang=fr&type=city&format=xml. You get the following result :

Errors

If there are errors in the input URL or if the query returns no toponyme, the API returns an error with a code and an error text in english. You can see below the error codes with their text :

• 1 : An API key is required
• 2 : Invalid API key
• 3 : Incorrect format ('json' and 'xml' allowed)
• 4 : You have to specify either a toponym name or a city code or a latitude and a longitude
• 5 : A language is required if you don't display a toponym randomly or if you don't search by city code or by coordinates
• 6 : Incorrect language ('oc' and 'fr' allowed)
• 7 : Incorrect department ('09', '12', '31', '32', '33', '40', '46', '47', '64', '65', '81' and '82' allowed)
• 8 : Incorrect type ('city' and 'country' allowed)
• 9 : You need to indicate either a type or a department if you don't display a toponym randomly or if you don't search by city code or by coordinates
• 10 : No toponym found with your specifications
• 11 : The 'ill' parameter only accepts the values 'true' and 'false'
• 12 : Incorrect variety ('lengadoc' and 'gascon' allowed)

Output informations

The output you get is a list of toponyms with an unique ID. For each one, you get :

• Its occitan name
• Its french name
• *Its department : with two numbers
• *Its type : "city" (world city) o "country" (world country)
• *Its latitude
• *Its longitude
• *Its city code
• *The URL of the picture which illustrates the expression
• *The author you have to credit if you use this picture
• *A fun fact in occitan about the city
• *A french translation of the fun fact about the city
• *The URL of the toponym page on the occitan Wikipedia
• *The fun fact variety

The fields with an * don't appear for each toponym.

Latitude, longitude and city code only appear for french territory cities.

Picture, author, fun fact and its translation, Wikipédia page and variety only appear for cities with an illustration.

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