Back to Home

POI Content

This document describes the REST interfaces for POIs. This document is part of the documentation for the REST API interfaces of the MD Content API.

Table of Contents

Search requests for POIs

General search for POI

The basic path to retrieving data from a general search is:

 http://api.123poi.com/data/poi/projection/all/?parameter=value

The result always contains all the information about a POI. These consist mainly of the Base POI and the Contributions. Contributions are stored in a language- and user-specific manner. This means that a user can only create one contribution per POI in one language. However, he can create a contribution in any language.

For the structure of the output format, please refer to the Output formats section.

User Story  As a user I want to retrieve all new POI. The POIs are sorted by lastUpdate, the latest POIs are output first.
HTTP GET
URL http://api.123poi.com/data/poi/api/all/

The result is a list of the most recently changed POIs.

User Story AnyUser looks for POI to a specific location
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?loc=Location

Example:

 GET http://api.123poi.com/data/poi/api/all/?loc=Berlin

Result is a list of POI whose city name contains Berlin. Exact hits are sorted to the beginning.

User Story AnyUser searches POI for a search term
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?search=SearchPhrase

Example:

 GET http://api.123poi.com/data/poi/api/all/?search=Nachts+im+Museum

The result is a list of POIs, which result in the above mentioned fields of a POI with the terms night, in the museum.

User Story AnyUser looks for POI over tags and finds all POIs that have this tag and are visible to it.
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?tag=TagName

Example:

 GET http://api.123poi.com/data/poi/api/all/?tag=Restaurant

Result is a list of POIs that have the tag restaurant.

User Story AnyUser searches POI in a travel guide and finds all the POIs that are mentioned and visible to this travel guide.
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?book=bookId

Example:

 GET http://api.123poi.com/data/poi/api/all/?book=12

The result is a list of POIs that are included in the guidebook with the bookId 12.Of course, the above parameter values can also be combined, which can limit the result to a smaller result quantity and thus a higher relevance.

User Story AnyUser searches for POI over tags, search terms, and location
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?tag=TagName&search=SearchPhrase&loc=Location

Example:

 GET http://api.123poi.com/data/poi/api/all/?tag=Museum&search=Bode&loc=Berlin

The result is a list of POIs to which the specified criteria apply. POI, which meet all three criteria are sorted forward.

Search in a user's POI

The basic path to retrieving data from a user-specific search is:

http://api.123poi.com/data/poi/projection/user/UserID/?parameter=value

The result always contains all the information about a POI.These consist of the main POI and the user's contributions.Since contributions are language- and user-specific, the contributions of other users are hidden.The BasePOI data is available because it can be that the contribution of a user has for example no address or geodata.For the structure of the output format, please refer to the Output formats section.

User Story As user I want to retrieve all new POI of a user. The POIs are sorted by lastUpdate, the latest POIs are output first.
HTTP GET
URL http://api.123poi.com/data/poi/projection/user/UserID/

The result is a list of the most recently changed POIs.

User Story AnyUser searches a user's POI to a specific location
HTTP GET
URL http://api.123poi.com/data/poi/projection/user/UserID/?loc=Location

Example:

GET http://api.123poi.com/data/poi/api/user/10/?loc=Berlin

Result is a list of POIs whose city name contains Berlin. Exact hits are sorted to the beginning.

User Story  AnyUser searches a user's POI for a search term
HTTP GET
URL http://api.123poi.com/data/poi/projection/user/UserID/?search=SearchPhrase

Example:

GET http://api.123poi.com/data/poi/api/user/10/?search=Nachts+im+Museum

The result is a list of POIs, which result in the above mentioned fields of a POI with the terms Nachts,im,Museum.

User Story AnyUser searches a user's POI over tags and finds all POIs that have this tag and are visible to it.
HTTP GET
URL http://api.123poi.com/data/poi/projection/user/UserID/?tag=TagName

Example:

 GET http://api.123poi.com/data/poi/api/user/10/?tag=Restaurant

Result is a list of POIs that have the tag restaurant.Of course, the above parameter values can also be combined, which can limit the result to a smaller result quantity and thus a higher relevance.

User Story AnyUser searches a user's POI over tags, keywords, and location
HTTP GET
URL http://api.123poi.com/data/poi/projection/user/UserID/?tag=TagName&search=SearchPhrase&loc=Location

Example:

 GET http://api.123poi.com/data/poi/api/user/10/?tag=Museum&search=Bode&loc=Berlin

The result is a list of POI of a user to which the specified criteria apply. POI, which meet all three criteria are sorted forward.

Searching in a BoundingBox

@|since: v1.0-alpha2

An additional parameter is specified for searching in a BoundingBox, see section Parameter values.

User Story AnyUser queries POI in a BoundingBox. The AnyUser-visible tags of the POI that are in this BoundingBox are returned.

``

Searching in a corridor

@|since: v5.0.5

For searching in a corridor, a POST request must be performed and the corridor must be given in the form of a line string and a distance in meters in the body.Optionally, the search can be limited by a BoundingBox. JSON and XML are supported as formats.

User Story AnyUser queries POIs in a corridor. The AnyUser visible POIs that are located in this corridor are returned.
HTTP POST
URL http://api.123poi.com/data/poi/projection/poicorridor

Example-JSON:

{"geometry": {
       "type":"LineString",
       "coordinates":[[9.18299,48.77582],[9.1854,48.78191],[9.17963,48.78457],...,[13.40495,52.52001]]},
       "distance":2000,
       "boundingBox":{
       "northwest":{"lat":52.6,"lon":9.1},
       "southeast":{"lat":48.7,"lon":13.5}
       }
    }

Example-XML:

<poi:poiCorridor xmlns:falkgeo="http://api.123poi.com/geo/" xmlns:poi="http://api.123poi.com/poi/
    <poi:geometry>
        <poi:type>LineString</poi:type>
        <poi:coordinates>
            <poi:coordinate>
                <falkgeo:lat>48.77582</falkgeo:lat>
                <falkgeo:lon>9.18299</falkgeo:lon>
            </poi:coordinate>
            <poi:coordinate>
                <falkgeo:lat>48.78191</falkgeo:lat>
                <falkgeo:lon>9.1854</falkgeo:lon>
            </poi:coordinate>
            ...
            <poi:coordinate>
                <falkgeo:lat>52.52001</falkgeo:lat>
                <falkgeo:lon>13.40495</falkgeo:lon>
            </poi:coordinate>
        </poi:coordinates>
    </poi:geometry>
    <poi:distance>2000</poi:distance>
    <poi:boundingBox>
        <falkgeo:northwest>
            <falkgeo:lat>52.6</falkgeo:lat>
            <falkgeo:lon>9.1</falkgeo:lon>
        </falkgeo:northwest>
        <falkgeo:southeast>
            <falkgeo:lat>48.7</falkgeo:lat>
            <falkgeo:lon>13.5</falkgeo:lon>
        </falkgeo:southeast>
    </poi:boundingBox>
</poi:poiCorridor>

Searching in a polygon

@|since: v5.0.5

For searching in a polygon, a POST request must be executed and the polygon must be entered in the body. No holes are currently supported.Optionally, the search can be limited by a BoundingBox. JSON and XML are supported as formats.

User Story AnyUser queries POIs in a polygon. The AnyUser visible POIs that are in this polygon are returned.
HTTP POST
URL http://api.123poi.com/data/poi/projection/poipolygon

Example-JSON:

{
     "geometry":{
        "type":"Polygon",
        "coordinates":[
          [[9.1305,48.793],[9.1267,48.7941],[9.1038,48.8039],...,[9.1305,48.793]]
        ]
      },
      "boundingBox":{
         "northwest":{"lat":52.6,"lon":9.1},
        "southeast":{"lat":48.7,"lon":13.5}
      }
    }

Example-XML:

<poi:poiPolygon xmlns:falkgeo="http://api.123poi.com/geo/" xmlns:poi="http://api.123poi.com/poi/
    <poi:geometry>
        <poi:type>Polygon</poi:type>
        <poi:coordinates>
            <poi:shell>
                <poi:coordinate>
                    <falkgeo:lat>48.793</falkgeo:lat>
                    <falkgeo:lon>9.1305</falkgeo:lon>
                </poi:coordinate>
                <poi:coordinate>
                    <falkgeo:lat>48.7941</falkgeo:lat>
                    <falkgeo:lon>9.1267</falkgeo:lon>
                </poi:coordinate>
                ...
                <poi:coordinate>
                    <falkgeo:lat>48.793</falkgeo:lat>
                    <falkgeo:lon>9.1305</falkgeo:lon>
                </poi:coordinate>
            </poi:shell>
        </poi:coordinates>
    </poi:geometry>
    <poi:boundingBox>
        <falkgeo:northwest>
            <falkgeo:lat>52.6</falkgeo:lat>
            <falkgeo:lon>9.1</falkgeo:lon>
        </falkgeo:northwest>
        <falkgeo:southeast>
            <falkgeo:lat>48.7</falkgeo:lat>
            <falkgeo:lon>13.5</falkgeo:lon>
        </falkgeo:southeast>
    </poi:boundingBox>
</poi:poiPolygon>

Circular search

@|since: v1.0-alpha4

An additional parameter is specified for circular search, see section Parameter values.

User Story AnyUser queries POIs within a given code. The AnyUser visible POIs, which are within the given search radius, are returned. The returned POIs are sorted by distance to the search center, the closer to the specified geocode, the higher up in the list. Featured POIs are displayed before normal POIs.

This query can be combined with other parameters.

  http://api.123poi.com/data/poi/api/all/?circle=52.52223,13.41637,25000&lang=de&tag=Restaurant

User Story * AnyUser queries POIs, so the POIs should be sorted so that the Customer's Featured POIs are displayed at the top. Featured POIs as well as the normal POIs are sorted according to relevance.*
HTTP GET
URL http://api.123poi.com/data/poi/projection/all/?sort=frel

To give preference to the FeaturedPOIs for a general search query, the parameter "sort" must be specified with the value "frel".

Examples:

 GET http://api.123poi.com/data/poi/api/all/?sort=frel
    
 GET http://api.123poi.com/data/poi/api/all/?sort=frel&search=Museum

@|since: v1.0-alpha3

Featured POIs are POI with a special value. They are delivered only to licensees who participate in one of our partner programs. In general, it is possible to query featured POIs in the same way as in the general search, with the special feature that a limited number of POIs (10) are delivered on the featured path by default, all of which are feature-rich. The order of the output is indeterminate, which is why it is not useful to scroll through the result set.

GET http://api.123poi.com/data/poi/api/featured
User Story AnyUser queries a defined number (maxCount) of randomly selected Featured POIs. Only Featured POIs will be returned, which should also be featured for this licensee.
HTTP GET
URL http://api.123poi.com/data/poi/api/featured/?itemsperpage=maxCount

When searching for Featured POIs on the "featured path" is the random sorting preset.

Example:

 GET http://api.123poi.com/data/poi/api/featured?itemsperpage=3
User Story AnyUser queries the Featured POIs to be sorted by relevance. Only Featured POIs of the customer are returned.
HTTP GET
URL http://api.123poi.com/data/poi/api/featured/?sort=SortValue&search=SearchValue&loc=Location

Example:

GET http://api.123poi.com/data/poi/api/featured?sort=rel&search=Hotel&loc=Stuttgart&itemsperpage=3&startindex=16

In this example, all feature POIs that are a hotel in Stuttgart are returned. In addition, max 3 POI are output per request, and in this case, from index 16, which corresponds to scrolling page 6.

Suggestions for search queries

There is a separate interface to get suggestions for search queries. This interface can be used by the browser via AJAX to search search queries with the entered fragments when entering search words in the background. The result can then be specified in the browser as a selection list.There are six different interfaces for general suggestions, tags, location, categories, destinations, and POI titles. In the case of the general proposals, the titles, the tags and the categories are scanned, in the proposals for tags only the tags are searched, cities, countries, countries, continents and tourist regions are searched for the proposals for venues. For the categories, only the categories are searched. The destination destinations are searched for the names of the destinations, including the names of the higher-level destinations.The search for tags can be restricted to a desired language via the long parameter. The search for titles and locations is additionally automatically restricted to visibility. Therefore, the suggestions for titles and for venues may differ depending on the user.The general suggestions and the suggestions for locations can be limited by a given bounding box. Only titles of POIs or locations that lie within the bounding box are then returned.The search for POI titles can be restricted to destinations (all POIs of the destination), alternatively the restriction on BoundingBox or perimeter is also supported.

User Story AnyUser wants to get suggestions for a general search, based on a word fragment, a word, or several words and word fragments. A list of tags, titles, and categories separated by line breaks is returned. The best matches are above.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/search?search=Fragment&lang=de
User Story AnyUser will get suggestions for a general search. The suggestions should only come from POIs within the given bounding box.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/search?search=Fragment&bbox=NWLat,NWLon,SELat,SELon
User Story AnyUser wants to receive suggestions for a tag search, based on a word fragment, a word, or several words and word fragments. A list of tags, separated by line breaks, is returned. The best matches are above.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/tag?search=Fragment
User Story AnyUser wants to receive suggestions for a location search, based on a word fragment, a word, or several words and word fragments. A list of locations (cities, states, countries, continents and tourist regions) is separated by line breaks. The best matches are above. In addition to the titles, the region type and the regionsId are returned, if available.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/loc?search=Fragment
User Story AnyUser will receive suggestions for a location search. Only locations that are within the specified bounding box should be returned.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/loc?search=Fragment&bbox=NWLat,NWLon,SELat,SELon
User Story AnyUser wants to receive suggestions for a category search, based on a word fragment, a word, or several words and word fragments. A list of categories, separated by line breaks, is returned. The best matches are above.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/cat?search=Fragment&lang=de
User Story AnyUser would like to receive suggestions for a destination search based on a word fragment, a word, or several words and word fragments. Returns a list of destinations separated by line breaks. The best matches are above. For more than one word fragment, the names of the overridden destinations are included in the search. Thus the search for "Stuttgart Deutschl" only provides the destination Stuttgart in Germany, not the Stuttgart in the USA.
HTTP GET
URL http://api.123poi.com/data/poi/api/suggest/destination?search=Fragment&lang=de
User Story AnyUser would like to suggest POIs based on words or word fragments and an optional geographic constraint. In addition to the POI title and the geocode, it should also return its ID, the location name (from the address), and the first category.
HTTP GET
URL

http://api.mairdumont.com/data/poi/api/suggest/poi?lang=de&search=Botschaft+usa&dest=34657

http://api.mairdumont.com/data/poi/api/suggest/poi?lang=de&search=Zoo&circle=48.84,9.07,15000

http://api.mairdumont.com/data/poi/api/suggest/poi?lang=de&search=Hotel&bbox=48.84,9.07,48.72,9.27

The restriction to destination is made via the parameter "dest". For performance reasons it is not searched for the polygon, but via the BoundingBox of the destination. The output is as JSON.

Example for POI proposals

  {
        "values": [
          {
            "poiId": 116791683,
            "title": "Burg Berwartstein",
            "category": {
              "id": 16,
              "name": "Essen & Trinken"
            },
            "coordinates": {
              "lat": 49.10857,
              "lon": 7.86364
            },
            "location": "Erlenbach bei Dahn",
            "highlight": "Burg Berwartstein, Essen & Trinken, Erlenbach bei Dahn",
            "highlightTerms": [
              "Burg Berwartstein",
              "Essen & Trinken",
              "Erlenbach bei Dahn"
            ],
            "extendedTitle": "Burg Berwartstein, Essen & Trinken, Erlenbach bei Dahn"
          },
          {
            "poiId": 115006669,
            "title": "Burg Berwartstein",
            "category": {
              "id": 13,
              "name": "Sehenswertes"
            },
            "coordinates": {
              "lat": 49.10856,
              "lon": 7.86364
            },
            "location": "Erlenbach",
            "highlight": "Burg Berwartstein, Sehenswertes, Erlenbach",
            "highlightTerms": [
              "Burg Berwartstein",
              "Sehenswertes",
              "Erlenbach"
            ],
            "extendedTitle": "Burg Berwartstein, Sehenswertes, Erlenbach"
          }
        ]
      }

Find all categories

The following path can be used to query all categories:

 http://api.123poi.com/data/poi/api/category/all?lang=de
User Story AnyUser would like to see all available categories and their IDs. All known categories are to be returned.
HTTP GET
URL http://api.123poi.com/data/poi/api/category/all?itemsperpage=1000

The categorie list can be output as an ATOM feed or in the JSON format. In addition to the names of the categories, the IDs and, if applicable, the ID of the upper category are also displayed.Example excerpt from the categorie list:

<feed>
      ...
      <data:category>
        <data:id>17</data:id>
        <data:name>Einkaufen & Shoppen</data:name>
      </data:category>
      ...
      <data:category>
        <data:id>1001</data:id>
        <data:parentId>10</data:parentId>
        <data:name>Vertragsschulen</data:name>
      </data:category>
      ...
    </feed>

Identify a single category with subcategories

A single category can be queried by its ID, which is then returned along with its subcategories.

User Story All categories belonging to a top category will be returned.
HTTP GET
URL http://api.123poi.com/data/poi/api/category/20?lang=de

Determine all used country codes (not available)

*A list of all country codes used by POIs can be queried. This functionality is currently not available.
*

User Story All countries should be returned regardless of statistics.
HTTP GET
URL http://api.123poi.com/data/poi/api/country/all

Operations on POI data (CRUD)

Creating a POI

User Story A user can create / change / delete / retrieve a POI (part 1: create)
HTTP POST
URL http://api.123poi.com/data/poi/api/poi

The data to be created must be specified in the corresponding XML format and must be specified in the request body. For this purpose, a suitable tool is used.As the content type, application / atom + xml is used. The data is posted as a new entry , example for an XML:

 POST http://api.123poi.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/">
       <id/>
       <title type="text">summ</title>
       <summary type="text"/>
       <updated>2010-05-26 17.04</updated>
       <published/>
       <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:publishedDate>1274886299296</poi:publishedDate>
             <poi:poidata>
               <poi:type>Contribution</poi:type>
               <poi:title>Gottlieb Daimler Stadion</poi:title>
               <data:language>de</data:language>
               <falkgeo:coordinates>
                 <falkgeo:lat>48.791599</falkgeo:lat>
                 <falkgeo:lon>9.229890</falkgeo:lon>
               </falkgeo:coordinates>
               <data:address>
                 <data:country>Deutschland</data:country>
                 <data:isoCountryCode>DE</data:isoCountryCode>
                 <data:zip>70173</data:zip>
                 <data:location>Stuttgart</data:location>
                 <data:subLocation/>
                 <data:street/>
                 <data:number>1</data:number>
               </data:address>
               <data:contact>
                 <data:phone/>
                 <data:fax/>
                 <data:web>http://www.gottlieb-daimler-stadion.de</data:web>
                 <data:email>info@gottlieb-daimler-stadion.de</data:email>
               </data:contact>
               <poi:tags>
                 <poi:tag>
                   <poi:value>Stadion</poi:value>
                 </poi:tag>
               </poi:tags>
             <poi:description>Statdion in Stuttgart</poi:description>
           </poi:poidata>
           <data:category>
             <data:id>20</data:id>
           </data:category>
         </poi:poi>
       </content>
     </entry>

A complete description of the format can be found in the documentation of the POI API XML Schema.

The result of this request informs the URL where the new POI can be reached.

Change a POI

User Story A user can create / change / delete / retrieve a POI (part 2: change)
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/PoiID/

A user can change a POI in two different ways.

  1. he adds a contribution to a POI
  2. he changes his contribution

Both operations use an HTTP-PUT request for this operation, the path of this operation points to the POI with its ID.

**Example:
**

 PUT http://api.123poi.com/data/poi/api/poi/6587945/
     
     <entry xmlns="http://www.w3.org/2005/Atom" 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/">
       <title type="text">Zeitgeschichtliches Forum Leipzig</title>
       <content type="application/atom+xml">
         <poi:poi>
           <poi:poidata>
             <poi:title>Zeitgeschichtliches Forum Leipzig</poi:title>
             <data:language>de</data:language>
     
             <data:contact>
               <data:phone>(03 41) 22 20-0</data:phone>
               <data:web>http://www.hdg.de/leipzig/</data:web>
               <data:email>zfl@hdg.de</data:email>
             </data:contact>
     
             <poi:tags>
               <poi:tag>
                 <poi:value>Museum</poi:value>
               </poi:tag>
             </poi:tags>
     
           </poi:poidata>
         </poi:poi>
       </content>
     </entry>

The input data format used here corresponds to that of a POST request. It is not necessary to re-send all the data, but only the data that is sent with a PUT request is changed. An exception to this rule are lists, such as tags, because it is necessary to retry the tags you want to keep.In the above example, phone, web, and e-mail would be added to the POI, the tag would be added to the tag 'museum', and the 'museums' tag previously given would be removed.

Delete a POI

User Story A user can create / change / delete / retrieve a POI (part 3: delete)
HTTP DELETE
URL http://api.123poi.com/data/poi/api/poi/PoiID/

n principle it is so that a user can delete his contribution to a POI. If, however, he is the one who created this POI and there are no other references to this POI, then the Base POI is also deleted. This is the "Aunt Erna principle", which allows users to remove data from the POI API again.Example of deleting the POI (or contribution):

DELETE http://api.123poi.com/data/poi/api/poi/6587945/

Quering a POI

User Story A user can create / change / delete / retrieve a POI (part 4: query)
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/PoiID/

Depending on the visibility of the POI, a guest, a friend or only the owner can query the POI.Example for querying the POI (or contribution):

 GET http://api.123poi.com/data/poi/api/poi/6587945/

Queries of possible duplicates

Before the POI is saved, a duplicate check can be executed, which returns duplicates. The criteria for a match is defined by the minimum request.

User Story A user can request possible duplicates before saving
HTTP POST
URL http://api.123poi.com/data/poi/api/check/poi

The content of the Pois, which is to be created or updated, is supplied as content. The duplicate check is carried out on the basis of these data. As a result, the poi Ids of the possible duplicates are returned.

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:exif="http://api.123poi.com/exif/" xmlns:poi="http://api.123poi.com/poi/" 
           xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
       <openSearch:totalResults>1</openSearch:totalResults>
       <openSearch:startIndex>0</openSearch:startIndex>
       <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
       <openSearch:Query role="request" poi:access="VISIBLE"/>
       <updated>2010-10-07T10:40:36.406Z</updated>
       <link href="http://api.123poi.com/data/poi/api/check/poi" rel="self"/>
       <title type="text">Dublettencheck</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/check/poi</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         <title type="text">Possible duplicate to 1</title>
         <link href="http://api.123poi.com/data/poi/api/poi/1" rel="alternate"/>
         <id>http://api.123poi.com/data/poi/api/poi/1</id>
         <summary type="text">Id: 1</summary>
         <content type="application/xml">
           <poi:duplicateIdentifier>
             <poi:contributorId>6</poi:contributorId>
             <poi:poiId>1</poi:poiId>
             <poi:matchingLevel>MINIMUM_MATCHING</poi:matchingLevel>
           </poi:duplicateIdentifier>
         </content>
       </entry>
     </feed>

Search Hints

Users with appropriate permission can extend a POI to include searchHints and locationHints. There, any terms can be stored, which should help to find the POI better. This is mainly used for Featured POIs. If at a POI in Bernhausen e.g. under locationHints the value "Stuttgart" is entered, so it is also found in a location search for Stuttgart.

**Example
**

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    
    <entry xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:data="http://api.123poi.com/data/" xmlns:user="http://api.123poi.com/user/">
      <title type="text">Zeitgeschichtliches Forum Leipzig</title>
      <content type="application/atom+xml">
        <poi:poi>
          <poi:searchHints>Osterfeuer Grillen</poi:searchHints>
          <poi:locationHints>Stuttgart</poi:locationHints>
        </poi:poi>
      </content>
    </entry>

Report POI as closed

A logged on user can report a POI as closed. The number of messages can be viewed via the "closedCount" field at the POI. However, the messages have no influence on the visibility or the order in result lists.A privileged user can close a POI using the same interface. Closed POIs are no longer included in searches, unless the requesting user has a contribution to the closed POI. It is also possible to directly query closed POIs. In these cases, closed POIs are marked via the "closed" field. The field is part of the default granulation.

User Story A logged on user can mark or close a POI as closed.
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/6587945/closed?reason=give a reason for closure

In order for a portal to be able to distinguish whether a POI has now been closed or has only been marked as closed, XML or JSON is returned with a status code in the event of success.For status code 1, the POI has only been marked as closed:

{"description":"POI marked as closed.","statusCode":"1"}

The POI was closed with status code 2:

{"description":"POI closed.","statusCode":"2"}

Operations on evaluation data (CRUD)

Create a rating

User Story A user can create / change / delete / retrieve a valuation (part 1: create)
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/6587945/

The data to be created must be specified in the corresponding XML format and must be specified in the request body. The creation of a valuation is done by updating the POI. All you have to do is enter the value of the valuation.The data is posted as a new entry , example for an XML:

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    
 <entry xmlns='http://www.w3.org/2005/Atom' 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/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value>10</poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>

Change a rating

User Story A user can create / change / delete / retrieve a rating (part 2: change)
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/6587945/

Similar to creating a rating, an update to the POI is made when you change a rating. A rating should be between 20 (equivalent to one star) and 100 (equivalent to 5 stars).

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    
 <entry xmlns='http://www.w3.org/2005/Atom' 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/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value>80</poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>

Delete a rating

User Story A user can create / change / delete / retrieve a rating (part 3: delete)
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/6587945/

Similar to the creation of a rating, an update to the POI is made when a rating is changed.

 PUT http://api.123poi.com/data/poi/api/poi/6587945/
    
<entry xmlns='http://www.w3.org/2005/Atom' 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/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value></poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>

Operations on external POI reviews (CRUD)

Create / change reviews

User Story As content manager, I would like to be able to retrieve and update reviews from partners as external reviews in the API. (Part 1: create, change)
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/6587945/critique/

The data to be created must be specified in the corresponding XML format and must be specified in the request body. For this purpose, a suitable tool is used.The data is posted as a new entry , example for an XML:

POST http://api.123poi.com/data/poi/api/poi/6587945/critique/
    
 <entry xmlns='http://www.w3.org/2005/Atom' xmlns:critique="http://api.123poi.com/critique/" xmlns:data="http://api.123poi.com/data/" xmlns:user="http://api.123poi.com/user/">
       <content type='application/atom+xml'>
         <critique:critiquePartnerSummary>
           <critique:summaryUrl>http://www.restaurant-kritik.de/183</critique:summaryUrl>
           <critique:averageScore>3.3</critique:averageScore>
           <critique:numberOfReviews>3</critique:numberOfReviews>
           <critique:partner>
             <user:id>17</user:id>
           </critique:partner>
           <critique:critiques>
             <critique:critique>
               <critique:externalId>187405</critique:externalId>
               <critique:externalServiceId>restaurantkritik_187405</critique:externalServiceId>
               <critique:score>4.0</critique:score>
               <critique:title>Hard Rock Café Berlin</critique:title> 
               <critique:comment>Das "Hard Rock Caf&eacute;" in Berlin ...</critique:comment>
               <critique:url>http://www.restaurant-kritik.de/bewertungen/187405</critique:url>
               <critique:creationDate>1336482056000</critique:creationDate>
               <critique:language>de</critique:language>
             </critique:critique>
           </critique:critiques>
         </critique:critiquePartnerSummary>
       </content>
     </entry>

A complete description of the format can be found in the documentation of the POI API XML-scheme.The result of this request is the URL where the new comment can be reached.

Querying of reviews

User Story A user can create / change / delete / retrieve a comment (part 2: retrieve all the reviews of a partner to a POI)
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/6587945/critique/

All reviews of a POI can be queried. You can also filter by partner (parameter 'partnerId') and language (parameter 'lang').

Operations on type of visit "I was already there" or "I would like to go there"

Create a visit type for POIs

User Story As a user I would like for a POI a visit type, whether I "was already there" or "I still want to go"
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/poiID/visited

The data to be created must be specified in the corresponding XML format and must be specified in the request body. For this purpose, a suitable tool is used.As the content type, application/atom+xml is used. The data is posted as a new entry , example for an XML:

 POST http://api.123poi.com/data/poi/api/poi/6587945/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' 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/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <poi:poi>
            <poi:visitedType>WOULD_LIKE_TO_VISIT</poi:visitedType>
        </poi:poi>
      </content>
    </entry>

Change a visit type for POIs

User Story As a user I would like to change the type of visit for a POI - "I was already there" or "I would like to go there"
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/poiID/visited

Example:

 PUT http://api.123poi.com/data/poi/api/poi/6587945/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' 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/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <poi:poi>
            <poi:visitedType>ALREADY_BEEN_THERE</poi:visitedType>
        </poi:poi>
      </content>
    </entry>

Querying which user has already visited the POI or still wants to

User Story  A POI is to be asked which user has already visited the POI or would like to visit the POI
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/poiID/?filter=visited

Create a visit type for destinations

User Story As a user I would like to be able to create a visit type to a destination - "I was already there" or "I would like to go there"
HTTP POST
URL http://api.123poi.com/data/destination/api/destination/destinationID/visited

The data to be created must be specified in the corresponding XML format and must be specified in the request body. For this purpose, a suitable tool is used.As the content type, application/atom+xml is used. The data is posted as a new entry , example for an XML:

 POST http://api.123poi.com/data/destination/api/destination/4/visited
     
    <entry xmlns='http://www.w3.org/2005/Atom' 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/" xmlns:destination="http://api.123poi.com/destination/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <destination:destination>
            <destination:visitedType>WOULD_LIKE_TO_VISIT</destination:visitedType>
        </destination:destination>
      </content>
    </entry>

Change a visit type for destinations

User Story As a user I would like to change to a destination the visit type - "I was already there" or "here I would still go"
HTTP PUT
URL http://api.123poi.com/data/destination/api/destination/destinationID/visited

Example:

 PUT http://api.123poi.com/data/destination/api/destination/4/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' 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/" xmlns:destination="http://api.123poi.com/destination/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <destination:destination>
            <destination:visitedType>ALREADY_BEEN_THERE</destination:visitedType>
        </destination:destination>
      </content>
    </entry>

Querying which users the destination has already visited or still want to visit

User Story A destination is to be asked, which users have already visited the destination, or which users would like to visit the destination
HTTP GET
URL http://api.123poi.com/data/destination/api/destination/destinationID/?filter=visited

Querying which POIs and destinations a user has already visited or would like to visit

User Story A user should be asked which destinations and POIs he has already visited or would like to visit
HTTP GET
URL http://api.123poi.com/data/poi/api/user/UserID/?filter=visited

Like It

Mark LikeIt on a contribution

Individual contributions should be evaluated by users via a "LikeIt". The contribution is identified by the user, the language of the contribution, and the poiId. Each user can only rate a contribution once. "LikeIt" is portal-wide, that is, If a contribution is provided with "LikeIt" on a portal, it is marked as "LikeIt" on other portals. When retrieving the contribution, it is included how many users like it and whether the currently logged-in user likes it.

User Story A user can mark a contribution as LikeIt
HTTP POST
URL http://api.123poi.com/data/poi/projection/user/UserID/poi/PoiID/likeit?lang=de

When retrieving the Pois, the LikeIt values are in the PoiData element:

 <feed xmlns="http://www.w3.org/2005/Atom" xmlns:exif="http://api.123poi.com/exif/" xmlns:poi="http://api.123poi.com/poi/" 
           xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
       <updated>2010-10-29T13:18:09.916Z</updated>
       <link href="http://api.123poi.com/data/poi/api/user/6/poi/115000254" rel="self"/>
       <title type="text">Inhalte eines Benutzers zu einem bestimmten Poi</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/user/6/poi/115000254</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         ...
         <content type="application/xml">
           <poi:poi xmlns:data="http://api.123poi.com/data/" xmlns:falkgeo="http://api.123poi.com/geo/" 
                    xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/">
           ...
             <poi:poidata>
               <poi:type>Contribution</poi:type>
               ...
               <data:language>de</data:language>
               ...
               <poi:likedCount>1</poi:likedCount>
               <poi:likes>true</poi:likes>
             </poi:poidata>
             ...
           </poi:poi>
         </content>
       </entry>
     </feed>

Remove LikeIt from a contribution

The logged-in user can remove his "LikeIt" from a contribution. The contribution is identified by the user, the language of the contribution, and the poiId.

User Story A user can remove his "LikeIt" from a contribution.
HTTP DELETE
URL http://api.mairdumont.com/data/poi//user//poi//likeit?lang=

Querying POIs with "LikeIt" on contribution

The logged-on user can query all POIs whose contribution he has set a "LikeIt". The normal visibility rules apply, that means the user has a contribution with "LikeIt" on another portal, but this POI is not visible on another portal, it will not be displayed in this portal if the user queries his contributions with "LikeIt". Browse, as well as the restriction to additional search criteria, is supported.

User Story A user can query all POIs whose contribution he has set a "LikeIt".
HTTP GET
URL http://testapi.mairdumont.com/data/poi/api/poi/likeit?lang=de

Info POIs

Info POIs are POI, which are subject to frequent changes, such as traffic jam reports. The supplied data correspond essentially to the geo projection and contain little additional information. The data is optimized for displaying objects in a map application, such as the Falk Map API.Info POIs are only available to selected users of the POI API.

Querying of the InfoPOIs by category

User Story A user can access all info POIs according to his categories
HTTP GET
URL http://api.123poi.com/data/poi/info/all/?cat=infoCategoryIDs

The Info POI can only be queried by category.Example for querying the InfoPOI:

GET http://api.123poi.com/data/poi/info/all/?cat=1,2

Querying all categories of InfoPOIs

Example for querying the InfoCategories List:All categories of InfoProjection can be queried using the following path:

User Story AnyUser would like to see all available categories and their IDs. All known categories are to be returned.
HTTP GET
URL http://api.123poi.com/data/poi/info/category/all

The categorie list can be output as an ATOM feed or in the JSON format.

Querying an InfoPOI by its category

User Story A user can only retrieve a POI.
HTTP GET
URL http://api.123poi.com/data/poi/info/poi/$poiid$/?cat=infoCategoryID

Depending on the visibility of the InfoPOI, you can query the POI.Example for querying the POI (or contribution):

 GET http://api.123poi.com/data/poi/info/poi/505110034/

Operations on cluster data

Querying of clusters

User Story A user can query for a BoundingBox cluster of a particular categroy for a zoom level
HTTP GET
URL http://api.123poi.com/data/poi/api/all/?filter=cluster&bbox=55,5,47,15&cat=7&zoomlevel=4&itemsperpage=100

You get the clusters for this BoundingBox and Zoomlevel. The request is leaf-sheet, i. If the parameter "itemsperpage" is not specified, one returns only 10 cluster by default.

Querying of the POIs of a cluster

User Story A user can query the contained POIs for clusters
HTTP GET
URL http://api.123poi.com/data/poi/api/cluster/6587945

The same rules for the sorting as for the other queries that supply a set of POIs apply to the query of POIs of a cluster.