Back to Home

Destination Content

This document describes operations with primary reference to destinations.

Table of Contents

Querying of Destinations and TravelInfos

To search destinations and TravelInfos, there are basically the two URLs

where a DestinationId or a TravelInfoId must be specified. The returned information differs depending on the URL and filter parameters.

The following filter parameter values are possible, but not all values are supported by both URLs: DESTINATION, TRAVELINFO, BREADCRUMB, PARENT, CHILDREN, INTERESTINGFOR, CONTAINEDIN, POI, TRAVELPOI and EVENT. The default value for the first URL is DESTINATION and TRAVELINFO for the second URL.

When returning TravelInfos, the result set can also be restricted to individual or several book series via the bookseries parameter.

Granulation

The path can be composed here:

">http://api.mairdumont.com/data/granulation/GranulierungsTreeSingleDestination.html

It is recommended to provide granulation only with the required fields for all queries. The fewer fields are queried, the faster queries can be answered. Just "media" and "mediastatistic" should be omitted if they are not needed for output.

Information about a destination

Querying a destination

User Story A user queries a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/500/?filter=destination
Information about a single destination comes back.

Querying the underdestinations (children) of a destination

User Story A user queries the children of a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/500/?filter=children&lang=de
There is a list with information about destinations. The list is empty if the requested destination has no offspring.

Querying of contained destinations (children + containedIn) of a destination

User Story A user asks for a destination all contained destinations.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/500/?filter=contains&lang=de
There is a list with information about destinations. All children of the destination and all destinations that are related to a containedIn-relation to the destination are returned. The list is empty if no matching destinations are found.

Querying of important destinations

User Story A licensee wants to be able to read the most important cities to a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/502/?filter=important&lang=de
There is a list of all destinations that are marked as important, which are subordinate to the specified destination. The list is empty if the requested destination has no important offspring. The list can be limited by 'itemsPerPage'.

Querying of destinations for which a destination is interesting

User Story  A user queries for a destination, for which destinations this is referenced as "interesting for".
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=interestingfor
There is a list with information about destinations. The list is empty if the queried destination has no referenced destinations.

Querying of interesting destinations for a destination

User Story A user queries the interesting destinations for a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=interesting
There is a list with information about destinations. The list is empty if the queried destination has no referenced destinations.
User Story A user queries for a destination the interesting destinations, and always wants to get a result.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=interestingplus
There is a list with information about destinations. If no interesting destinations are found, the destinations are returned with a travel reference nearby. Based on the attribute destinationRelationType, you can see if there are interesting destinations or travel destinations nearby.

Querying of nearby destinations with travel cover for a destination

User Story A user queries to a destination nearby destinations with travel cover.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=travelrelated
There is a list with information about destinations. The list contains only destinations that are travel relevant.

Querying of contained destinations for a destination

User Story A user queries for a destination as "contain-in" reverted destinations of type 'Travel-Region'.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=containedin
There is a list of information about destinations (travel regions only). The list is empty if the requested destination has no referenced destinations, or if the travel region does not have, for the inquirer; view-based TravelInfo objects.

Querying travel information for a destination

User Story A user queries the travel information for a destination in a desired language. (The language must be specified). The travel information will be returned to the requested destination in the desired language. Travel information for children must be requested separately.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/177098/?filter=travelinfo&lang=de
There is a list of travel information. The list is empty if no visible travel information has been found.

Querying parent destinations (breadcrumb)

User Story A user asks for a destination the superior destinations to the world. Both the direct path via the parent destination and the paths should be returned via referenced destinations.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/113804/?filter=breadcrumb&lang=de
There is a list of lists of slimmed down destinations. The first list contains the path to the parent destination. The following lists contain the alternate routes.

Querying the statistics of a destination

User Story A user queries a destination statistics.
HTTP GET
URL  http://api.mairdumont.com/data/destination/api/destination/500/:(statistic)?lang=de
There is statistical information about a single destination for the current customer. The statistics are created for, as well as number of destination pois, number of highlights, number of destination POIs per category, whether the premium POIs are present, whether the BestOf tours are available, and the list with TravelInfo Sub TextTypes, etc. Some statistics depend on the language, for example the number of sub-destinations as well as the number of destinations included.

Restriction

The statistics are generated according to the customer for performance reasons and are only available under separate conditions.

Searching

Searching for destinations

User Story A user searches for destinations based on a word fragment, a word, or several words. The best matches should be returned.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/all?lang=de&search=destination%20names 
Example http://api.mairdumont.com/data/destination/api/destination/all?lang=de&search=New+York+USA
Destinations of type "TravelRegion" are only returned if the licensee has visible travel information.

Searching for destinations in a BoundingBox

User Story A user searches for destinations, based on a BoundingBox. All destinations are found whose Geocode is within this BoundingBox
HTTP GET
URL  http://api.mairdumont.com/data/destination/api/destination/all?bbox=,,,
Example   http://api.mairdumont.com/data/destination/api/destination/all?bbox=67.2,12.1,37.6,16.2
Destinations of type "TravelRegion" are only returned if the licensee has visible travel information.

Querying of POIs for a destination

User Story A user queries the referenced POIs for a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/113804/?filter=poi
There is a list with information about POIs. The list is empty if the queried destination has no referenced POIs.

Querying of editorially assigned POIs for a destination

User Story A user queries the POIs for a destination that are assigned to a book series. Only visible book series are considered the POI assignments. POIs which are editorially assigned to an underdestination are also returned.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/113804/?filter=travelpoi
There is a list with information about POIs. The list is empty if the queried destination has no referenced POIs or Visible TravelInfos.

Querying of editorially marked POIs for a destination

User Story A user queries for a destination the POIs that have been editorially marked for a book series. Only visible book series are considered the POI assignments. POIs that are awarded in a subdestination will not be returned. Possible values for the award are: TOP_HIGHLIGHT, HIGHTLIGHT, TOP_INSIDER_TIP, INSIDER_TIP, CONTAINED_IN, INTERESTING_FOR, LUXURY, GOURMET.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=poi&commendation=highlight,insider_tip
There is a list with information about POIs. The list is empty if the queried destination does not have any referenced POIs or visible TravelInfos.
User Story A user queries for a destination the editorial marks of the POIs, which are editorially marked in a book series.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/:(commendation)/?filter=poi&commendation=highlight,insider_tip
There is a list of POI awards. The list is empty if the queried destination does not have any referenced POIs or visible TravelInfos.

Querying of the editorial-assigned POIs of a travel guide volume for a destination

User Story A user queries the POIs for a destination that are contained in a travel guide. Assignments to other travel guides of the same series are not taken into account. POIs, which are distinguished in a subdestination, are also returned with.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=travelpoi&buch=
There is a list with information about POIs. The list is empty if the queried destination does not have any referenced POIs or visible TravelInfos.

The bookID should be identified by an additional request http://api.123poi.com/data/destination/api/destination/4/?filter=travelinfo&lang=de, as this changes with a new edition of the travel guide.

You can specify a list of bookIDs and search in multiple guides at the same time. The value none is used to get all POIs that are not in a travel guide.

http://api.mairdumont.com/data/destination/api/destination/4/?filter=poi&buch=7,none

User Story A user queries for a destination the POIs that have been specially selected for editorial purposes. Ratings in other travel guides of the same series are not considered. POIs, which are distinguished in a subdestination, are also returned with. Possible values for the award are:TOP_HIGHLIGHT, HIGHTLIGHT, TOP_INSIDER_TIP, INSIDER_TIP, CONTAINED_IN, INTERESTING_FOR, LUXURY, GOURMET.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=travelpoi&buch=$buchId$&commendation=highlight,insider_tip

Querying of destinations where the specified geocode is included

User Story A user queries a geocode for all destinations that contain this geocode.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/destination/all/:(name,type,coordinates,bbox)?geocode=48.2,11.6
Example 
{
        "entries": [{
            "destinationId": 23931,
            "destinationName": "München",
            "destinationType": "ADMIN_CITY",
            "boundingBox": {
                "northwest": {
                    "lat": 48.248123,
                    "lon": 11.3605883
                },
                "southeast": {
                    "lat": 48.0616006,
                    "lon": 11.7229192
                }
            },
            "coordinates": {
                "lat": 48.1372719,
                "lon": 11.5754815
            },
            "creationDate": 1355826691588,
            "creationDateFormatted": "2012-12-18 11:31:31 +0100",
            "lastUpdate": 1372070807348,
            "lastUpdateFormatted": "2013-06-24 12:46:47 +0200"
        }, {
            "destinationId": 6506,
            "destinationName": "Bayern",
            "destinationType": "ADMIN_REGION",
            "boundingBox": {
                "northwest": {
                    "lat": 50.5647336,
                    "lon": 8.976069
                },
                "southeast": {
                    "lat": 47.2700987,
                    "lon": 13.8397906
                }
            },
            "coordinates": {
                "lat": 48.9468034,
                "lon": 11.4189768
            },
            "creationDate": 1353910921493,
            "creationDateFormatted": "2012-11-26 07:22:01 +0100",
            "lastUpdate": 1372059868176,
            "lastUpdateFormatted": "2013-06-24 09:44:28 +0200"
        }, {
            "destinationId": 5618,
            "destinationName": "Germany",
            "destinationType": "ADMIN_COUNTRY",
            "boundingBox": {
                "northwest": {
                    "lat": 54.91740036010739,
                    "lon": 5.8694429397583
                },
                "southeast": {
                    "lat": 47.28110122680661,
                    "lon": 15.038049697876
                }
            },
            "coordinates": {
                "lat": 51.10046848648669,
                "lon": 10.395422469532143
            },
            "creationDate": 1355825924651,
            "creationDateFormatted": "2012-12-18 11:18:44 +0100",
            "lastUpdate": 1361456195802,
            "lastUpdateFormatted": "2013-02-21 15:16:35 +0100"
        }],
        "totalResults": 3,
        "startIndex": 0,
        "itemsPerPage": 10,
        "searchTime": 0
    }
There is a list with information about destinations. The list is empty if no destination contains this geocode.

Querying of destinations (Breadcrumb) in which the specified geocode is included

User Story A user queries to a geocode all destinations in the form of Breadcrumbs that contain this geocode.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/destination/all?filter=breadcrumb&geocode=39.614152,2.987852  
Example 
{
        "entries": [{
            "destinationIdentifier": [{
                "destinationId": 500,
                "destinationName": "World",
                "destinationType": "ADMIN_WORLD"
            }, {
                "destinationId": 502,
                "destinationName": "Europe",
                "destinationType": "ADMIN_CONTINENT"
            }, {
                "destinationId": 5719,
                "destinationName": "Spanien",
                "destinationType": "ADMIN_COUNTRY"
            }, {
                "destinationId": 7638,
                "destinationName": "Illes Balears",
                "destinationType": "ADMIN_REGION"
            }, {
                "destinationId": 78627,
                "destinationName": "Lloret de Vistalegre",
                "destinationType": "ADMIN_CITY"
            }]
        }, {
            "destinationIdentifier": [{
                "destinationId": 500,
                "destinationName": "World",
                "destinationType": "ADMIN_WORLD"
            }, {
                "destinationId": 502,
                "destinationName": "Europe",
                "destinationType": "ADMIN_CONTINENT"
            }, {
                "destinationId": 5719,
                "destinationName": "Spanien",
                "destinationType": "ADMIN_COUNTRY"
            }, {
                "destinationId": 7638,
                "destinationName": "Illes Balears",
                "destinationType": "ADMIN_REGION"
            }, {
                "destinationId": 177097,
                "destinationName": "Mallorca",
                "destinationType": "TRAVEL_REGION"
            }, {
                "destinationId": 177101,
                "destinationName": "Die Inselmitte",
                "destinationType": "TRAVEL_REGION"
            }]
        }],
        "searchTime": 0
    }
There comes a list of destination-breadcrumbs. The list is empty if no destinations contain this geocode.

Querying of destinations with travel information in which the specified geocode is included

User Story A user queries for a geocode all destinations with travel information that contains this geocode. The destinations are sorted by relevance.
HTTP GET
URL

http://api.mairdumont.com/data/poi/api/destination/all?filter=traveldestination&lang=de&itemsperpage=1&geocode=39.567308,2.647859&country=ESP
Example 
  {
        "entries": [
          {
            "destinationId": 79042,
            "destinationName": "Palma de Mallorca",
            "destinationType": "ADMIN_CITY",
            "coordinates": {
              "lat": 39.5695824,
              "lon": 2.6500714
            },
            "creationDate": 1355835039700,
            "creationDateFormatted": "2012-12-18 13:50:39 +0100",
            "lastUpdate": 1447324544704,
            "lastUpdateFormatted": "2015-11-12 11:35:44 +0100",
            "breadcrumb": "Palma de Mallorca, Balearische Inseln, Spanien"
          }
        ],
        "totalResults": 5,
        "startIndex": 0,
        "itemsPerPage": 1,
        "searchTime": 304
      }
The results list is empty if no destination with travel information contains the geocode. The "country" parameter is optional and is used in the case of overlapping city polygons in the border region. The two-digit as well as three-digit ISO 3166 country code can be used as the value.
User Story A user asks for a destination, which connects with which bookmarks / tours.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=folder
There is a list with information about Folder. The list is empty if the queried destination has no referenced folders.

Querying events for a destination

User Story A user queries the referenced events for a destination.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/4/?filter=event
There is a list of information about events. The list is empty if the queried destination has no referenced events.

TravelInfos

Querying a travel information (portal)

User Story A user queries a travel information for a destination in a portal. The language is necessary.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/destination/2/?filter=travelinfo&lang=de
All visible travel information from origin OUT is returned.

Querying of travel information (editorial system)

User Story An editor queries an editorial travel information for a destination. The language is necessary.
HTTP GET
URL http://api.mairdumont.com/data/destination/editor/destination/2/?filter=travelinfo&lang=de
All visible travel information from the origin PRINT and WEB will be returned.

Querying of travel information by text type and sub type (portal)

User Story An editor queries an editorial travel information for a destination by text type and optional subtext type.
HTTP GET
URL  http://api.mairdumont.com/data/destination/api/destination/2/?filter=travelinfo&lang=de&texttype=pseudo_poi&subtype=fooddrink&book=3
All visible travel information from origin OUT to TextType and optional SubTextype will be returned.

Querying of travel information by text type and sub type (editorial system)

User Story An editor queries an editorial travel information for a destination by text type and optional subtext type.
HTTP GET
URL  http://api.mairdumont.com/data/destination/editor/destination/2/?filter=travelinfo&lang=de&texttype=pseudo_poi&subtype=fooddrink&book=3
All visible travel information from the origin PRINT and WEB is returned by text type and optional subtext type.

Querying the child travel information (children) of travel information

User Story A user queries the subordinate travel information for a travel information.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/travelinfo/2/?filter=children
There is a list of travel information. The list can be empty if no visible travel information was found.

Querying, changing and deleting climate information

User Story A user queries, changes, or deletes the climate table.
HTTP GET, PUT, DELETE
URL http://api.mairdumont.com/data/destination/api/travelinfo/2/weather
HTTP-GET: The climatic table comes back, if it exists.

HTTP-PUT: The climate table is created or, if already existing, overwritten.

 <entry xmlns="http://www.w3.org/2005/Atom" xmlns:destination="http://api.123poi.com/destination/" >
       <content type="application/atom+xml">
               <destination:weather>
                   <destination:headline>Wetter in Berlin</destination:headline>
                   <destination:weatherTables>
                       <destination:weatherTable>
                           <destination:name>Tagestemperaturen in C°</destination:name>
                           <destination:unit>C°</destination:unit>
                           <destination:type>day</destination:type>
                           <destination:values>
                               <destination:value>2</destination:value>
                               <destination:value>3</destination:value>
                               <destination:value>8</destination:value>
                               <destination:value>13</destination:value>
                               <destination:value>19</destination:value>
                               <destination:value>22</destination:value>
                               <destination:value>24</destination:value>
                               <destination:value>23</destination:value>
                               <destination:value>19</destination:value>
                               <destination:value>13</destination:value>
                               <destination:value>7</destination:value>
                               <destination:value>3</destination:value>
                           </destination:values>
                       </destination:weatherTable>
                   </destination:weatherTables>
               </destination:weather>
       </content>
     </entry>

Querying of a TravelInfo text

User Story A user queries a TravelInfo text.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/doc/${docID}
A TravelInfo text including all items is returned.

Possible types of TravelInfo texts (destination:textType):

Querying of a TravelInfo article

User Story A user queries a TravelInfo text.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/doc/${docID}/article/${articleID}
A single article is returned.

Querying travel information with embedded texts and articles

User Story A user queries a travel information for a destination in a portal. All travel texts and articles (of the desired type) should already be included.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/destination/5641/:(destinationid,isbookinfo,name,book,travelinfotexts)?filter=travelinfo&lang=de&texttype=pseudo_poi&subtype=sightseeing&book=66
Instead of retrieving the texts and articles individually, it is also possible with granulation to query them directly with the travel information. Since large amounts of data are possibly processed, e.g. for country destinations, these requests should be subject to other restrictions, e.g. text type or book.

Searching TravelInfo texts by tags

User Story A user searches for TravelInfo texts by tags.
HTTP GET
URL http://api.mairdumont.com/data/destination/api/doc/all?tag=
The tag list can include comma separating multiple tags. These tags are then linked to the search or, i.e. texts are returned that contain at least one of the tags you are looking for. If you insert + at the beginning of the tag list, the tags are linked, i.e. only texts with all the specified tags will be returned.

Data structure of a TravelInfo object

Basic structure of a TravelInfo

Travelinfo

{
    "id": 20548,
    "destinationId": 77657,
    "isBookInfo": true,
    "name": "Barcelona",
    "book": { /* Info zum Reiseführer */ },
    "travelInfoTexts": [ { /* TravelInfoText */ } ],
    "weather": { /* {KlimaInfo} */ },
    "creationDate": 1385641028703,
    "creationDateFormatted": "2013-11-28 13:17:08 +0100",
    "lastUpdate": 1412240772318,
    "lastUpdateFormatted": "2014-10-02 11:06:12 +0200"
    }

Structure of a TravelInfoText:

TravelinfoText

{
     "id": 116831,
     "textType": "CHAPTER",
     "title": "Praktische Hinweise",
     "subtitle": "Von Anreise bis Zoll",
     "edition": "2014-16",
     "subtype": "traveltips",
     "teaser": "Urlaub von Anfang bis Ende: die wichtigsten Adressen und Informationen f&uuml;r Ihre Barcelona-Reise",
     "travelInfoArticles": [
      {
         "id": 221288,
         "docID": 116831,
         "headline": "Anreise",
         "text": "..."
         "articleSubType": "gettingThere",
         "creationDate": 1385641020450,
         "creationDateFormatted": "2013-11-28 13:17:00 +0100",
         "lastUpdate": 1444296898537,
         "lastUpdateFormatted": "2015-10-08 11:34:58 +0200"
      },
      { /* travelInfoArticle */ }
     ],
     "author": {"id": 13, "name": "Marco Polo", "profileImage": "http://pic.123poi.com/api/content/logos/13/icon/icon.gif"},
     "creationDate": 1385641020448,
     "creationDateFormatted": "2013-11-28 13:17:00 +0100",
     "lastUpdate": 1443775435478,
     "lastUpdateFormatted": "2015-10-02 10:43:55 +0200"
    }

Book-specific description texts for POIs

Contributions are limited to one description text. In order for a POI to have a different description text, depending on the volume requested, book-specific descriptions were introduced.

When creating a POI, these book-specific descriptions can be specified. The book is then referenced through its ExternalId, which is found in XML3 of the volume, along with the type of volume (region or city), which is also given. In addition, the source of the description text is also specified. In addition to the print text, a special text can also be created for the web or app.

The description texts for different books can be added, updated or deleted by updates to the contribution of the POI. It is not necessary to provide all the descriptions for all books every time. Existing description texts are identified by the ExternalId of the book and the source. To delete a description text, you must update with an empty description text.

The best description text is selected from the various descriptions. The Web and App sources have priority over print. The volume type city has priority over region. Finally, the length of the texts decides. The best description text is set as a description of the contribution, and thus delivered. Any existing description text of the contribution will be overwritten.

If the POI is to be queried in the context of a specific book, the book parameter can be used to specify that the best description text of the specified book should be returned as a description text.

The book-specific description texts are not part of the default granulation. They can, however, be queried via the granulation: (poidata:(traveldescription)).

Creation of a POI with book-specific description texts

User Story A user can create book-specific description texts for his contribution
HTTP POST
Header Content-Type: application/atom+xml
URL http://api.mairdumont.com/data/poi/api/poi/ 
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
      <content type="application/atom+xml">
        <poi:poi xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/">
          <poi:poidata>
            <poi:title>Gottlieb Daimler Stadion</poi:title>
            <data:language>de</data:language>
            <user:author><user:id>6</user:id></user:author>
            <falkgeo:coordinates>
              <falkgeo:lat>48.791599</falkgeo:lat>
              <falkgeo:lon>9.229890</falkgeo:lon>
            </falkgeo:coordinates>
            <data:address>
              <data:isoCountryCode>DE</data:isoCountryCode>
              <data:location>Stuttgart</data:location>
              <data:zip>70173</data:zip>
            </data:address>
            <data:travelDescriptions>
              <data:travelDescription>
                <data:bookExternalId>MP_Ligurien_Aufl2008/11_DE_region</data:bookExternalId>
                <data:bookLevelOfDetail>REGION</data:bookLevelOfDetail>
                <data:origin>PRINT</data:origin>
                <data:description>POI-Beschreibung für Ligurien-Band (Print).</data:description>
              </data:travelDescription>
              <data:travelDescription>
                <data:bookExternalId>MP_Ligurien_Aufl2008/11_DE_region</data:bookExternalId>
                <data:bookLevelOfDetail>REGION</data:bookLevelOfDetail>
                <data:origin>WEB</data:origin>
                <data:description>POI-Beschreibung für Ligurien-Band (Web).</data:description>
              </data:travelDescription>
              <data:travelDescription>
                <data:bookExternalId>MP_Rom_Aufl2008/15_DE_city</data:bookExternalId>
                <data:bookLevelOfDetail>CITY</data:bookLevelOfDetail>
                <data:origin>APP</data:origin>
                <data:description>POI-Beschreibung für Rom-Band (App).</data:description>
              </data:travelDescription>
            </data:travelDescriptions>
          </poi:poidata>
          <data:category>
            <data:id>20</data:id>
          </data:category>
        </poi:poi>
      </content>
    </entry>

Destination Quick Facts

Destinations can have Quick Facts. This is information about the best travel time, the travel categories, the power plug-ins and whether a visa is required for a visit. In case of doubt, this information always refers to the german view, e.g. the field "powerAdapterRequired" always refers to devices manufactured for the german market (adapter C/F).Some information is inherited from subordinate destinations (e.g. Germany) to the underlying destinations (see "Inheritance" column, for example "powerPlugTypes"). This information is thus centrally maintained at a destination, but can also be viewed at all the destinations below.

Field name Description Heredity Example (JSON)
bestTravelMonths A list of the best travel month, with ID and localized name. 0 stands for January, 1 for February, 11 for December. no [ { "id": 2, "name": "March" }, { "id": 9, "name": "October" } ]
powerPlugTypes List of connector types, e.g. for the representation of the connector types. yes [ "C", "F" ]
powerPlugDescription The list of connector types for display as text. yes "C, F"
powerPlugVoltage The current voltage in volts (may contain commas or hyphens). yes "230"
powerPlugFrequency The frequency in Hertz (may contain commas or hyphens). yes "50"
powerPlugAdapterRequired Whether a travel adapter is needed to connect german devices. Possible values are "YES", "NO" and "PARTIAL", as well as to reset the value "NULL" yes "NO"
visaRequired Whether a german passport or a visa is required. Possible values are "TRUE" and "FALSE", as well as to reset the value "NULL". yes "FALSE"
visaURL A URL containing further information on visa requirements, e.g. By the Federal Foreign Office. yes "">http://www.auswaertiges-amt.de/DE/Laenderinformationen/00-SiHi/Nodes/AegyptenSicherheit_node.html"
travelCategories A list of the travel categories for which the destination is particularly suitable. no [ { "id": 4, "name": "Ocean" }, { "id": 2, "name": "Shopping" } ]

Querying list of supported travel categories

User Story Querying the list of supported travel categories.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/destination/category/all?lang=de
ID travel category
1 Culture
2 Shopping
3 Outdoor
4 Ocean
5 Sea
6 Winter Sports
7 Celebrations

Querying destination Quick Facts

User Story Querying destination QuickFacts to a destination or a list of destinations
HTTP GET
URL

http://api.mairdumont.com/data/poi/api/destination/37067?lang=de

http://api.mairdumont.com/data/poi/api/destination/all?lang=de&search=Neustadt
The Destination QuickFacts are output with the other destination information as standard, both for individual requests as well as for lists. The fields can be individually selected via the granulation.

Example output

  {
        "entries": [
          {
            "destinationId": 37067,
            "destinationName": "Hamburg",
            "destinationType": "ADMIN_CITY",
            "parentId": 5618,
            "bestTravelMonths": [
              {
                "id": 2,
                "name": "März"
              },
              {
                "id": 9,
                "name": "Oktober"
              }
            ],
            "powerPlugTypes": [
              "C",
              "F"
            ],
            "powerPlugDescription": "C, F",
            "powerPlugVoltage": "230",
            "powerPlugFrequency": "50",
            "powerPlugAdapterRequired": "NO",
            "visaRequired": "FALSE",
            "visaURL":  "http://www.auswaertiges-amt.de/DE/Laenderinformationen/00-SiHi/Nodes/AegyptenSicherheit_node.html" ,
            "travelCategories": [
              {
                "id": 4,
                "name": "Meer"
              },
              {
                "id": 2,
                "name": "Shopping"
              }
            ]
          }
        ] 
     }

Restrict destination search to Quick Facts

When searching for destinations, search parameters can be specified in order to only display destinations with the desired properties. The possible search parameters are "months", "visa" and "travelcat". The search parameters can be combined with each other and with other search parameters. For the parameters "months" and "travelcat", several values can be separated by commas. With the parameter "travelcat", the search can be adapted by means of a preceding plus sign, so that the destinations must meet all specified travel categories instead of only one.

User Story Restrict destination search to Quick Facts.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/destination/all?lang=de&travelcat=+4,7&visa=false&months=7,8,9

http://api.mairdumont.com/data/destination/api/destination/5641?lang=de&filter=interestingplus&travelcat=+4,7
Parameter Values Description
months Numbers between 0 (January) and 11 (December), several months may be indicated by commas, e.g. "4,5,6". Only destinations with at least one of the specified months as the best travel time are displayed.
visa "true" or "false" Only destinations that require a visa (true) or not (false) are displayed. The visa information is inherited in principle to the lower destination, but inherited properties are ignored for the search. Only destinations with the property directly set are displayed.
travelcat IDs from the list of well-known travel categories. Several travel categories may be indicated by commas, e.g. "4.7". If a destination should have all the specified travel categories, a plus sign can be prepended, e.g. "+4.7". Only destinations with at least one or all (pre-defined plus signs) travel categories are displayed.

Travel time for destinations

Restrict destination search on travel duration (and travel type)

When searching for destinations, search parameters can be specified to only display destinations within the desired travel period. The possible search parameters are "minDuration", "maxDuration" and "meansOfTravel". The search parameter "meansOfTravel" alone has no effect. If only one of the two parameters "minDuration" and "maxDuration" is specified, 0 or infinity is assumed.

User Story Restrict destination search on travel time.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/destination/all?lang=de&minDuration=120&maxDuration=300&meansOfTravel=TRAIN

http://api.mairdumont.com/data/destination/api/destination/5641?lang=de&filter=interestingplus&maxDuration=60&meansOfTravel=CAR
Parameter Values Description
minDuration The minimum duration of travel in minutes, e.g. "60". Only destinations where the duration of travel with the desired travel type(s) is above the specified time will be displayed. If no trip type (parameter "meansOfTravel") is specified, all trips will be considered.
maxDuration The maximum duration of travel in minutes, e.g. "200". Only destinations where the duration of travel with the desired travel type(s) under the specified time is displayed. If no trip type (parameter "meansOfTravel") is specified, all trips will be considered.
meansOfTravel The planned travel mode. Possible values are CAR, TRAIN and AIRCRAFT, respectively 0, 1, 2. Several travel modes can be combined by comma, e.g. "CAR, TRAIN". Only destinations that can be reached with the specified travel dates in the specified travel period are displayed. If a destination can only be reached by airplane, it would not be delivered with "meansOfTravel = TRAIN". If a destination can be reached by airplane in 2 hours and by train in 3 hours, the request "meansOfTravel = TRAIN & maxDuration = 120" would not meet the destination. The query "meansOfTravel = AIRCRAFT, maxDuration = 120", however, already.

Querying language guides for destinations

If a destination is queried or searched, linked language guides are output with.

User Story A user would like to display the linked language guides for a destination.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/destination/

http://api.mairdumont.com/data/destination/api/destination/all?search=

Example output

"languageGuides":[

      {

         "id":10,

         "language":"fr",

         "bookSeriesIdentifier":"MPLG",

         "creationDate":1422486000000,

         "creationDateFormatted":"2015-01-29 00:00:00 +0100",

         "lastUpdate":1422486000000,

         "lastUpdateFormatted":"2015-01-29 00:00:00 +0100"

      }

   ]

User Story A user would like to see a complete language guide.For this purpose, a language guide can be loaded directly, or the referenced language guides can also be output with the granularity of languageguides.
HTTP GET
URL

http://api.mairdumont.com/data/destination/api/languageguide/

http://api.mairdumont.com/data/destination/api/destination//:(languageguides)

Example output

{
   "entries":[
      {
         "id":24,
         "documents":[
            {
               "id":79,
               "title":"Sprachführer Französisch",
               "subtitle":"",
               "teaser":"Dami....",
               "articles":[
                  {
                     "id":64,
                     "headline":"Basics",
                     "text":"Text ...",
                     "teaser":"",
                     "creationDate":1423053000208,
                     "creationDateFormatted":"2015-02-04 13:30:00 +0100",
                     "lastUpdate":1423053000208,
                     "lastUpdateFormatted":"2015-02-04 13:30:00 +0100"
                  },
                  {
                     "id":65,
                     "headline":"Anreise",
                     "text":"Text ...",
                     "teaser":"",
                     "creationDate":1423053000210,
                     "creationDateFormatted":"2015-02-04 13:30:00 +0100",
                     "lastUpdate":1423053000210,
                     "lastUpdateFormatted":"2015-02-04 13:30:00 +0100"
                  }
               ],
               "author":{
                  "id":13,
                  "name":"Marco Polo",
                  "profileImage":"http://testpic.123poi.com/api/content/logos/13/icon/icon.gif"
               },
               "metaInformation":{
                  "title":"Französisch",
                  "keywords":"",
                  "description":""
               },
               "creationDate":1423053000204,
               "creationDateFormatted":"2015-02-04 13:30:00 +0100",
               "lastUpdate":1423053000204,
               "lastUpdateFormatted":"2015-02-04 13:30:00 +0100"
            }
         ],
         "language":"fr",
         "bookSeriesIdentifier":"MPLG",
         "destinations":[
            {
               "destinationId":5611,
               "destinationName":"France",
               "destinationType":"ADMIN_COUNTRY"
            }
         ],
         "creationDate":1423053000144,
         "creationDateFormatted":"2015-02-04 13:30:00 +0100",
         "lastUpdate":1423053000144,
         "lastUpdateFormatted":"2015-02-04 13:30:00 +0100"
      }
   ],
   "searchTime":111
}