API & modules

API top'Òc - Notice

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 :

{
    "query": [
        {
            "id": 1248,
            "oc": "Aush",
            "fr": "Auch",
            "dep": "32",
            "lat": "43.65",
            "long": "0.583333",
            "cityCode": "32013"
        }
    ]
}

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 :

{
    "query": [
        {
            "id": 4357,
            "oc": "Bol\u00edvia",
            "fr": "Bolivie",
            "type": "country"
        }
    ]
}

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 :

{
    "query": [
        {
            "id": 3056,
            "oc": "Aast",
            "fr": "Aast",
            "dep": "64",
            "lat": "43.2833",
            "long": "-0.083333",
            "cityCode": "64001"
        }
    ]
}

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 :

{
    "query": [
        {
            "id": 1038,
            "oc": "Mur\u00e8th",
            "fr": "Muret",
            "dep": "31",
            "lat": "43.4667",
            "long": "1.35",
            "cityCode": "31395"
        }
    ]
}

Le paramètre facultatif

You can choose to display only toponyms that are illustrated by a picture and a sound 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 :

{
    "query": [
        {
            "id": 2591,
            "oc": "Caramauç",
            "fr": "Carmaux",
            "dep": "81",
            "lat": "44.05",
            "long": "2.15",
            "cityCode": "81060",
            "url": "https://www.locongres.org/oc/aplicacions/top-oc/passejada/9815",
            "picture": "https://www.locongres.org/images/ciutats/caramauc",
            "anecdoteOc": "s'i trabalha lo veire",
            "anecdoteFr": "on y travaille le verre"
        }
    ]
}

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 :

{
    "query": [
        {
            "id": 3566,
            "oc": "Sibrac dau Med\u00f2c",
            "fr": "Civrac-en-M\u00e9doc",
            "dep": "33",
            "lat": "45.3333",
            "long": "-0.9",
            "cityCode": "33128"
        }
    ]
}

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 :

{
    "query": [
        {
            "id": 1993,
            "oc": "Sant Miard",
            "fr": "Saint-Medard-Nicourby",
            "dep": "46",
            "lat": "44.7667",
            "long": "2.05",
            "cityCode": "46282"
        }
    ]
}

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 :

<query>
    <top id="4585">
        <oc>Bratislava</oc>
        <fr>Bratislava</fr>
        <type>city</type>
    </top>
</query>

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'

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
  • *The URL of the full article on Lo Congrès website
  • *An anecdote in occitan about the city
  • *A french translation of the anecdote about the city

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

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

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

DTD XML

<! ELEMENT query (top) >

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

<! ELEMENT top (anecdoteOc?, anecdoteFr?, cityCode?, dep?, fr, lat, long, oc, picture?, pictureCredit?, type?, url?) >
<! ATTLIST top id ID #REQUIRED >

<! ELEMENT anecdoteOc (#PCDATA) >

<! ELEMENT anecdoteFr (#PCDATA) >

<! ELEMENT cityCode (#PCDATA) >

<! ELEMENT dep (#PCDATA) >

<! ELEMENT fr (#PCDATA) >

<! ELEMENT lat (#PCDATA) >

<! ELEMENT long (#PCDATA) >

<! ELEMENT oc (#PCDATA) >

<! ELEMENT picture (#PCDATA) >

<! ELEMENT pictureCredit (#PCDATA) >

<! ELEMENT type (#PCDATA) >

<! ELEMENT url (#PCDATA) >

© Lo Congrès Permanent de la Lenga Occitana, 2017, all rights reserved - Contact Lo Congrès