{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d465c3dd-f8d7-4b1e-a3fe-12f196711be5","name":"suedtirol.live - Public API","description":"The suedtirol.live API (SL API) is your gateway to South Tyrol's largest database of POI, tour/activity and event data. It powers the website of suedtirol.live and other connected sites and partners.\n\n## Events API\n\nGet access to all events of South Tyrol's and its surrounding regions. The SL Event API for example powers South Tyrol's largest and most popular event calendar kultur.bz.it and connected partners.\n\n## Places API\n\nGet access to our database of POIs including accommodations, sights, stores, gastronomy and many more. The SL Places API powers for example South Tyrol's #1 gastronomy guide restaurants.st as well as South Tyrol's shopping guide shopping.st.\n\n**Right now the Places API is available for accommodations and stores with their own endpoint. Other types of POIs will be available at a future point in time.**\n\n## Tours API\n\nGet access to all tours in South Tyrol and make your way through the most beautiful landscapes. The SL API provides you all the information you need like the difficulty, duration and distance of the tour.\n\n## Activities API\n\nGet access to all activities in South Tyrol and its surrounding regions. Whether they are organized by a local artisan or any other provider for leisure activities, find all activities that are taking place in a single call.\n\n## Search API\n\nThe Search API is a powerful tool granting you access to the whole database with a lot of possibilities to filter your results.\n\n## Geography API\n\nUse the geography calls to look up any data related to any entity. In the SL API every entity is bound to a unified set of city, region, county and country data.\n\n## How to apply for an API key\n\nTo be able to use our endpoints please don't hesitate to apply for an API key. Based on your wish you will get access to exactly the endpoints you need.  \nSend an email to\n\n```\nsupport@firstavenue.it\n\n ```\n\nto apply and get your key today.\n\n## Endpoint\n\nThe API is accessed by making HTTP requests to the endpoint\n\n```\nhttps://api.suedtirol.live\n\n ```\n\n## Sandbox (Test System)\n\nThe endpoint for the SL API sandbox is\n\n```\nhttps://api-sandbox.suedtirol.live\n\n ```\n\nIn case you need access to the sandbox please contact us.\n\nNote: IDs (e.g. for types and properties) can be different on our Sandbox. You should always make sure to use the specific GET calls to request the IDs valid for the environment.\n\n## Requests\n\nThe SL API is built with common techniques based on HTTP requests and JSON responses. To have access to the API you need to have an API key. Please use the following structure for your HTTP header with every call to the SL API:\n\n- Authorization: APIKEY {{api_key}}\n- Accept: application/x.sl.v1+json\n- Content-Type: application/json\n- Accept-Language: {{language}}\n    \n\nPossible languages:\n\n- de_DE\n- it_IT\n- en_EN\n    \n\n## Responses\n\nEach response will be delivered in the same language as given in the request's HTTP header.\n\nThe response objects are wrapped in a data tag. This means that the main information for the requested objects will always be within a data field.\n\nThe response can either consist of a single object or a list of objects. In the latter case the data field will be an array which contains the result objects and the response will look as follows:\n\n``` json\n{\n    \"data\": [\n        {\n            \"id\": 1234,\n            \"class\": 1,\n            \"title\": \"Example Place\",\n            ...\n        },\n        {\n            \"id\": 2345,\n            \"class\": 1,\n            \"title\": \"Another Place\",\n            ...\n        }\n    ],\n    ...\n}\n\n ```\n\n**If not mentioned otherwise the following rules apply**\n\n- String/Character values that are not filled return \"\"\n- Int/Decimal/Date values that are not filled return null\n- Data objects that are not filled and can contain max 1 object return null\n- Data objects that are not filled and can contain n objects return an empty array\n    \n\n**Errors will return with a message telling you what went wrong as well as an HTTP status code:**\n\n``` json\n{\n    \"status_code\": 401,\n    \"message\": \"Failed to authenticate because of bad authorization header.\",\n    \"code\": 401,\n    \"errors\": [\n        {\n            \"code\": 401,\n            \"title\": \"Failed to authenticate because of bad authorization header.\"\n        }\n    ]\n}\n\n ```\n\n## Paging Results\n\nIf your response contains a list of objects the SL API will provide you a pagination field within the response:\n\n``` json\n{\n    \"data\": [\n        ...\n    ],\n    \"meta\": {\n        \"pagination\": {\n            \"total\": 100,\n            \"count\": 25,\n            \"per_page\": 25,\n            \"current_page\": 2,\n            \"total_pages\": 4,\n            \"links\": {\n                \"previous\": \"https://api.suedtirol.live/public/places?page=1\",\n                \"next\": \"https://api.suedtirol.live/public/places?page=3\"\n            }\n        }\n    }\n}\n\n ```\n\n| Field | Description |\n| --- | --- |\n| total | Overall number of found objects |\n| count | Number of objects on the current page. |\n| per_page | Number of max. objects on each page |\n| current_page | Current page |\n| total_pages | Total number of pages |\n| links | Links to previous and next page if available |\n\n**For navigating through the results you can use the following query string parameters:**\n\n| Query String Parameter | Required | Description |\n| --- | --- | --- |\n| page | optional | Set the page number of the result set (default: 0) |\n| size | optional | Set the number of results per page (default: 50) |\n\nExamples:\n\n```\nhttps://api.suedtirol.live/public/events?page=2&size=15\n\n ```\n\n## Caching\n\nPlease\n\n- use a sensible caching concept for your use cases\n- avoid similar and repetitive calls and avoid ad-hoc requests\n    \n\nIn case you need to use ad-hoc requests against the API, please contact us.\n\n## Need Help?\n\nPlease contact us if you have any questions. Send your requests and questions to\n\n```\nsupport@firstavenue.it\n\n ```\n\nWe are glad to help you.\n\n---\n\n# Update History\n\n20.8.2020 Added functionality to POST and PATCH \"Events API > Import API\" routes, that maps old IDs automatically to new IDs for: organizer_id, place_id (inside dategroups), sponsor_id. This means an API client does not necessarily need to update its mappings. The API also returns information about new mappings in a new \"meta\" return object. Please refer to the Import API specification for more details.\n\n17.8.2020 Added new routes PATCH and DELETE for \"Events API > Import API\"\n\n17.02.2020 Updated the section \"Introduction\". The POI API for stores and accommodations and their calls are now located in the section \"Places API\".\n\n17.10.2019 GET /events(/:id): Added \"origin\" field (premium only)\n\n15.01.2019 In GET /events(/:id) you will find two more deeplinks to use and either link out to suedtirol.live, kultur.bz.it or cultura.tn.it\n\n01.10.2018 We have introduced an API sandbox in case you require or want to implement against a test system. This should only be necessary in very specific cases. If you believe you need access to the sandbox please contact us.\n\n27.09.2018 Added \"is_certified\" field in GET /events/:id. This field indicates that an event was reviewed by the kultur.bz.it editorial team.\n\n21.09.2018 Based on your feedback we have introduced an alternative, eventually more easy representation of the events date structure. Refer to the GET /events/:id call for more information.\n\n21.06.2018 Added filter \"organizer\" in GET /events\n\n17.04.2018 \"GET /events/:id\": \"sale_link\" was moved to the \"translation\" object as it can be different in multiple languages\n\n09.03.2018 Updated section \"Export API - Response\" with empty value rules\n\n12.02.2018 Added FAQ section\n\n05.02.2018 Updated Export and Import API developer information for all calls\n\n21.01.2018 Added Import API XML example file\n\n14.11.2017, We have improved the EVENTS API subscription model. The API will now return only events that are selected as per your subscription type and detail.\n\n21.09.2017, The Events API can now be accessed via https. We recommend doing so as we will disable http access in the future.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"2567447","team":57557,"collectionId":"d465c3dd-f8d7-4b1e-a3fe-12f196711be5","publishedId":"SVYrrxkg","public":true,"publicUrl":"https://apidoc.suedtirol.live","privateUrl":"https://go.postman.co/documentation/2567447-d465c3dd-f8d7-4b1e-a3fe-12f196711be5","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.11.4","publishDate":"2019-08-06T11:35:44.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/54176b44703c99d9e602b4af5a446cad3c276641cb7809cc773db7dd7a6d7c29","favicon":"https://suedtirol.live/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://apidoc.suedtirol.live/view/metadata/SVYrrxkg"}