API documentation

Geographical data

Read out Geo-IDs and City-IDs

Data sets with the geographical tree.

API: GeoTree/ISO

Chapters:

API: GeoTree/ISO

Function

Enables queries using ISO country codes (2 digits), or ISO-3166-2 region codes. Outputs the geographical tree.

URL for requests

To retrieve the data, use the following URL. Please pay attention to upper case lower case.

Request parameters

With the following variables you can complete the query and control the API results.

Parameter Explanation Examples
api_key
required

Your API Key

?api_key=abc-123-def-456
ISO
required
ISO country code, 2 digits, or
Region code according to ISO 3166-2
&ISO=DE-BW
cities

Flag for extended export with recorded cities:

Variants:
0 = Without Cities (= default)
1 = Including Cities

&cities=1
charset

The desired coding of the response

Variants:
UTF-8 (= default)
ISO-8859-1

&charset=iso-8859-1
format

The desired output format

Variants:
JSON (= default)
XML
CSV

&format=xml
hl

Desired language of the output

Variants:
de = German (= default)
fr = French
it = Italian
en = English

&hl=en

Return values of the API

The contents of the API responses result from:
- the data you have subscribed to (countries, public holidays, school holidays, calendar years)
- the officially known data of the legislators
- the availability based on our research (ACTUAL situation of our database)

Please note that the output in CSV format differs.

Array         Explanation Example
interface         Version of the API  
source: href       URL to the data source (website)  
  description       Name of the data source  
copyright href       URL to the copyright holder (website)  
  description       Designation of the copyright holder  
apiName         Identification of the API GeoTree/ISO
apiStatus description       Designation of the API status. For variants, see the Error messages active
date         Date of the data export 08.08.2022
request: iso       ISO country code, 2 digits BE
  charset       Font coding of the output utf-8
  format       Output data format json
  hl       Language of issue, according to request en
results status description     Output status. For variants, see the Error messages ok
  location       Geographical unit according to request  
    description     Designation of the geographical unit Belgium
    type     Designation of the type of geographical unit Country
    geoId     Geo-ID of the geographical unit. 3285
    iso     ISO country code, 2 digits BE
    iso-3166-2     Region code according to ISO 3166-2  
    cities     Any cities and towns covered in this region  
      description      
      cityId      
    children     Any subordinate geographical units  
      description   Designation of the geographical unit Brussels
      type   Designation of the type of geographical unit Region
      geoId   Geo-ID of the geographical unit. 3288
      iso   ISO country code, 2 digits BE
      iso-3166-2   Region code according to ISO 3166-2 BE-BRU
      cities   Any cities and towns covered in this region  
      children   Any subordinate geographical units
(up to 4 levels are possible)
array

Error messages

Output location Error message Explanation
results: status:
results: status: description unknown location The requested ISO country code is not known.
Please check the parameter ISO
apiStatus
apiStatus: description invalid usage The use of this API is not activated for you.
Please contact our support.
apiStatus: description invalid key Invalid API key.
Please check your API key.
apiStatus: description invalid referer Invalid access. Links from web pages (front-ends) are not allowed.
Set up your query so that it comes from a protected back-end.
If necessary, contact our support.
apiStatus: description inactive The API has not yet been activated for you to use.
Please try again at a later date.
apiStatus: description expired The period of use according to the contract has expired.
Contact our administration for a contract extension.

Examples

JSON

URL:
https://feiertagskalender.ch/api/GeoTree/ISO/?api_key=YOUR_API_KEY&iso=BE&cities=1

Response from the API:

{
   "interface":"fcal API 2.0",
   "source":{
      "href":"https://feiertagskalender.ch",
      "description":"feiertagskalender.ch"
   },
   "copyright":{
      "href":"https://psc.ch",
      "description":"psc Peter Schuetz Informatik-Dienstleistungen, CH Bern"
   },
   "apiName":"GeoTree/ISO",
   "apiStatus":{
      "description":"active"
   },
   "date":"2022-08-08",
   "request":{
      "iso":"BE",
      "charset":"utf-8",
      "format":"json",
      "hl":"de"
   },
   "results":{
      "status":{
         "description":"ok"
      },
      "location":{
         "description":"Belgien",
         "type":"Land",
         "geoId":"3285",
         "iso":"BE",
         "iso-3166-2":"",
         "cities":null,
         "children":[
            {
               "description":"Bruxelles",
               "type":"Region",
               "geoId":"3288",
               "iso":"BE",
               "iso-3166-2":"BE-BRU",
               "cities":[
                  {
                     "description":"Brussels",
                     "cityId":"1785"
                  },
                  {
                     "description":"Brussels Airport",
                     "cityId":"23711"
                  }
               ],
               "children":null
            },
            {
               "description":"Flandre",
               "type":"Region",
               "geoId":"3286",
               "iso":"BE",
               "iso-3166-2":"BE-VLG",
               "cities":null,
               "children":[
                  {
                     "description":"Antwerpen",
                     "type":"Provinz",
                     "geoId":"3546",
                     "iso":"BE",
                     "iso-3166-2":"BE-VLG",
                     "cities":[
                        {
                           "description":"Antwerp",
                           "cityId":"2468"
                        },
                        {
                           "description":"Turnhout",
                           "cityId":"25501"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Limburg",
                     "type":"Provinz",
                     "geoId":"3548",
                     "iso":"BE",
                     "iso-3166-2":"BE-VLG",
                     "cities":[
                        {
                           "description":"Hasselt",
                           "cityId":"10377"
                        },
                        {
                           "description":"Maasmechelen",
                           "cityId":"16268"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Oost-Vlaanderen",
                     "type":"Provinz",
                     "geoId":"3545",
                     "iso":"BE",
                     "iso-3166-2":"BE-VLG",
                     "cities":[
                        {
                           "description":"Ghent",
                           "cityId":"2738"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Vlaams-Brabant",
                     "type":"Provinz",
                     "geoId":"3547",
                     "iso":"BE",
                     "iso-3166-2":"BE-VLG",
                     "cities":[
                        {
                           "description":"Leuven",
                           "cityId":"3488"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"West-Vlaanderen",
                     "type":"Provinz",
                     "geoId":"3544",
                     "iso":"BE",
                     "iso-3166-2":"BE-VLG",
                     "cities":[
                        {
                           "description":"Bruges",
                           "cityId":"3318"
                        },
                        {
                           "description":"De Panne",
                           "cityId":"3368"
                        },
                        {
                           "description":"Ostend",
                           "cityId":"12368"
                        }
                     ],
                     "children":null
                  }
               ]
            },
            {
               "description":"Wallonnie",
               "type":"Region",
               "geoId":"3287",
               "iso":"BE",
               "iso-3166-2":"BE-WAL",
               "cities":null,
               "children":[
                  {
                     "description":"Henegouwen",
                     "type":"Provinz",
                     "geoId":"3549",
                     "iso":"BE",
                     "iso-3166-2":"BE-WAL",
                     "cities":[
                        {
                           "description":"Charleroi",
                           "cityId":"3348"
                        },
                        {
                           "description":"Endingen",
                           "cityId":"366"
                        },
                        {
                           "description":"Mons",
                           "cityId":"3538"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Luik",
                     "type":"Provinz",
                     "geoId":"3551",
                     "iso":"BE",
                     "iso-3166-2":"BE-WAL",
                     "cities":[
                        {
                           "description":"Ans",
                           "cityId":"12538"
                        },
                        {
                           "description":"Liège",
                           "cityId":"1935"
                        },
                        {
                           "description":"Verviers",
                           "cityId":"11158"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Luxemburg",
                     "type":"Provinz",
                     "geoId":"3553",
                     "iso":"BE",
                     "iso-3166-2":"BE-WAL",
                     "cities":[
                        {
                           "description":"Arlon",
                           "cityId":"10397"
                        },
                        {
                           "description":"Bastogne",
                           "cityId":"8608"
                        },
                        {
                           "description":"Liezen",
                           "cityId":"8618"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Namur",
                     "type":"Provinz",
                     "geoId":"3552",
                     "iso":"BE",
                     "iso-3166-2":"BE-WAL",
                     "cities":[
                        {
                           "description":"Namur",
                           "cityId":"3558"
                        }
                     ],
                     "children":null
                  },
                  {
                     "description":"Waals-Brabant",
                     "type":"Provinz",
                     "geoId":"3550",
                     "iso":"BE",
                     "iso-3166-2":"BE-WAL",
                     "cities":[
                        {
                           "description":"Ottignies-Louvain-la-Neuve",
                           "cityId":"16257"
                        }
                     ],
                     "children":null
                  }
               ]
            }
         ]
      }
   }
}

XML

URL:
https://feiertagskalender.ch/api/GeoTree/ISO/?api_key=YOUR_API_KEY&iso=BE&cities=1&format=xml

Response from the API:

<fcal_api>
	<interface>fcal API 2.0</interface>
	<source>
		<href>https://feiertagskalender.ch</href>
		<description>feiertagskalender.ch</description>
	</source>
	<copyright>
		<href>https://psc.ch</href>
		<description>psc Peter Schuetz Informatik-Dienstleistungen, CH Bern</description>
	</copyright>
	<apiStatus>
		<description>active</description>
	</apiStatus>
	<apiName>GeoTree/ISO</apiName>	
	<date>2022-08-08</date>
	<request>
		<iso>BE</iso>
		<charset>utf-8</charset>
		<format>xml</format>
		<hl>de</hl>
	</request>
	<results>
		<status>
			<description>ok</description>
		</status>
		<location>
			<description>Belgien</description>
			<type>Land</type>
			<geoId>3285</geoId>
			<iso>BE</iso>
			<iso-3166-2></iso-3166-2>
			<cities></cities>
			<children>
				<child>
					<description>Bruxelles</description>
					<type>Region</type>
					<geoId>3288</geoId>
					<iso>BE</iso>
					<iso-3166-2>BE-BRU</iso-3166-2>
					<cities>
						<city>
							<description>Brussels</description>
							<cityId>1785</cityId>
						</city>
					</cities>
					<children></children>
				</child>
				<child>
					<description>Flandre</description>
					<type>Region</type>
					<geoId>3286</geoId>
					<iso>BE</iso>
					<iso-3166-2>BE-VLG</iso-3166-2>
					<cities></cities>
					<children>
						<child>
							<description>Antwerpen</description>
							<type>Provinz</type>
							<geoId>3546</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-VLG</iso-3166-2>
							<cities>
								<city>
									<description>Antwerp</description>
									<cityId>2468</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Limburg</description>
							<type>Provinz</type>
							<geoId>3548</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-VLG</iso-3166-2>
							<cities>
								<city>
									<description>Hasselt</description>
									<cityId>10377</cityId>
								</city>
								<city>
									<description>Maasmechelen</description>
									<cityId>16268</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Oost-Vlaanderen</description>
							<type>Provinz</type>
							<geoId>3545</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-VLG</iso-3166-2>
							<cities>
								<city>
									<description>Ghent</description>
									<cityId>2738</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Vlaams-Brabant</description>
							<type>Provinz</type>
							<geoId>3547</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-VLG</iso-3166-2>
							<cities>
								<city>
									<description>Leuven</description>
									<cityId>3488</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>West-Vlaanderen</description>
							<type>Provinz</type>
							<geoId>3544</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-VLG</iso-3166-2>
							<cities>
								<city>
									<description>Bruges</description>
									<cityId>3318</cityId>
								</city>
								<city>
									<description>De Panne</description>
									<cityId>3368</cityId>
								</city>
								<city>
									<description>Ostend</description>
									<cityId>12368</cityId>
								</city>
							</cities>
							<children></children>
						</child>
					</children>
				</child>
				<child>
					<description>Wallonnie</description>
					<type>Region</type>
					<geoId>3287</geoId>
					<iso>BE</iso>
					<iso-3166-2>BE-WAL</iso-3166-2>
					<cities></cities>
					<children>
						<child>
							<description>Henegouwen</description>
							<type>Provinz</type>
							<geoId>3549</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-WAL</iso-3166-2>
							<cities>
								<city>
									<description>Charleroi</description>
									<cityId>3348</cityId>
								</city>
								<city>
									<description>Endingen</description>
									<cityId>366</cityId>
								</city>
								<city>
									<description>Mons</description>
									<cityId>3538</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Luik</description>
							<type>Provinz</type>
							<geoId>3551</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-WAL</iso-3166-2>
							<cities>
								<city>
									<description>Ans</description>
									<cityId>12538</cityId>
								</city>
								<city>
									<description>Liège</description>
									<cityId>1935</cityId>
								</city>
								<city>
									<description>Verviers</description>
									<cityId>11158</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Luxemburg</description>
							<type>Provinz</type>
							<geoId>3553</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-WAL</iso-3166-2>
							<cities>
								<city>
									<description>Arlon</description>
									<cityId>10397</cityId>
								</city>
								<city>
									<description>Bastogne</description>
									<cityId>8608</cityId>
								</city>
								<city>
									<description>Liezen</description>
									<cityId>8618</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Namur</description>
							<type>Provinz</type>
							<geoId>3552</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-WAL</iso-3166-2>
							<cities>
								<city>
									<description>Namur</description>
									<cityId>3558</cityId>
								</city>
							</cities>
							<children></children>
						</child>
						<child>
							<description>Waals-Brabant</description>
							<type>Provinz</type>
							<geoId>3550</geoId>
							<iso>BE</iso>
							<iso-3166-2>BE-WAL</iso-3166-2>
							<cities>
								<city>
									<description>Ottignies-Louvain-la-Neuve</description>
									<cityId>16257</cityId>
								</city>
							</cities>
							<children></children>
						</child>
					</children>
				</child>
			</children>
		</location>
	</results>
</fcal_api>                  

CSV

Aufruf:
https://feiertagskalender.ch/api/GeoTree/ISO/?api_key=YOUR_API_KEY&iso=BE&cities=1&format=csv

Response from the API:

"location_L0";"type_L0";"geoId_L0";"iso_L0";"iso-3166-2_L0";"location_L1";"type_L1";"geoId_L1";"iso_L1";"iso-3166-2_L1";"location_L2";"type_L2";"geoId_L2";"location_L3";"type_L3";"geoId_L3";"location_L4";"type_L4";"geoId_L4";"cityName";"cityId"
"Belgien";"Land";"3285";"BE";"";"";"";"";"";"";"";"";"";"";"";"";"";"";"";"";""
"Belgien";"Land";"3285";"BE";"";"Bruxelles";"Region";"3288";"BE";"BE-BRU";"";"";"";"";"";"";"";"";"";"";""
"Belgien";"Land";"3285";"BE";"";"Bruxelles";"Region";"3288";"BE";"BE-BRU";"";"";"";"";"";"";"";"";"";"Brussels";"1785"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"";"";"";"";"";"";"";"";"";"Brussels";"1785"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Antwerpen";"Provinz";"3546";"";"";"";"";"";"";"";""
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Antwerpen";"Provinz";"3546";"";"";"";"";"";"";"Antwerp";"2468"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Limburg";"Provinz";"3548";"";"";"";"";"";"";"Antwerp";"2468"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Limburg";"Provinz";"3548";"";"";"";"";"";"";"Hasselt";"10377"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Limburg";"Provinz";"3548";"";"";"";"";"";"";"Maasmechelen";"16268"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Oost-Vlaanderen";"Provinz";"3545";"";"";"";"";"";"";"Maasmechelen";"16268"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Oost-Vlaanderen";"Provinz";"3545";"";"";"";"";"";"";"Ghent";"2738"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Vlaams-Brabant";"Provinz";"3547";"";"";"";"";"";"";"Ghent";"2738"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"Vlaams-Brabant";"Provinz";"3547";"";"";"";"";"";"";"Leuven";"3488"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"West-Vlaanderen";"Provinz";"3544";"";"";"";"";"";"";"Leuven";"3488"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"West-Vlaanderen";"Provinz";"3544";"";"";"";"";"";"";"Bruges";"3318"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"West-Vlaanderen";"Provinz";"3544";"";"";"";"";"";"";"De Panne";"3368"
"Belgien";"Land";"3285";"BE";"";"Flandre";"Region";"3286";"BE";"BE-VLG";"West-Vlaanderen";"Provinz";"3544";"";"";"";"";"";"";"Ostend";"12368"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"West-Vlaanderen";"Provinz";"3544";"";"";"";"";"";"";"Ostend";"12368"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Henegouwen";"Provinz";"3549";"";"";"";"";"";"";"";""
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Henegouwen";"Provinz";"3549";"";"";"";"";"";"";"Charleroi";"3348"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Henegouwen";"Provinz";"3549";"";"";"";"";"";"";"Mons";"3538"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Henegouwen";"Provinz";"3549";"";"";"";"";"";"";"Endingen";"366"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luik";"Provinz";"3551";"";"";"";"";"";"";"Endingen";"366"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luik";"Provinz";"3551";"";"";"";"";"";"";"Liège";"1935"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luik";"Provinz";"3551";"";"";"";"";"";"";"Verviers";"11158"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luik";"Provinz";"3551";"";"";"";"";"";"";"Ans";"12538"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luxemburg";"Provinz";"3553";"";"";"";"";"";"";"Ans";"12538"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luxemburg";"Provinz";"3553";"";"";"";"";"";"";"Bastogne";"8608"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luxemburg";"Provinz";"3553";"";"";"";"";"";"";"Liezen";"8618"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Luxemburg";"Provinz";"3553";"";"";"";"";"";"";"Arlon";"10397"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Namur";"Provinz";"3552";"";"";"";"";"";"";"Arlon";"10397"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Namur";"Provinz";"3552";"";"";"";"";"";"";"Namur";"3558"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Waals-Brabant";"Provinz";"3550";"";"";"";"";"";"";"Namur";"3558"
"Belgien";"Land";"3285";"BE";"";"Wallonnie";"Region";"3287";"BE";"BE-WAL";"Waals-Brabant";"Provinz";"3550";"";"";"";"";"";"";"Ottignies-Louvain-la-Neuve";"16257"
                
Pages
Partner projects
©2003 - 2022 psc Peter Schütz Informatik Dienstleistungen, CH-Bern