Open POI Service

Overview

The Open Point of Interest (POI) service provides a RESTful API to find points of interest near a location. Such points of interest can be restaurants, stores, sights, parks, or other geographical features. You can query the API using latitude and longitude World Geodetic System 1984 (WGS84) coordinates and a radius parameter in meters. The result contains the locations and descriptions of points of interest within the radius. The API returns data in GeoJSON format which you can easily include in custom applications.

API Reference

/search

get

Return a GeoJSON FeatureCollection, which includes all points of interest that match the query criteria, ordered by their distance from the reference point.

Request
Response

Headers

Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
```
Bearer access_token
```

Query Parameters

long: required (number)
Defines the longitude of the WGS84 coordinate pair describing the location to search for points of interest.
Example:
```
8.68453
```
lat: required (number)
Defines the latitude of the WGS84 coordinate pair describing the location to search for points of interest.
Example:
```
49.411323
```
radius: required (number)
Specifies the radius of the search area in meters.
Example:
```
150
```

HTTP status code 200

The request was successful

Body

Type: application/json

Example:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.68382,
          49.41065
        ]
      },
      "properties": {
        "distance": 139.66,
        "name": "Neckarinsel",
        "asciiName": "Neckarinsel",
        "featureDescription": "island",
        "countryCode": "DE"
      }
    }
  ]
}

HTTP status code 400

Bad request

Body

Type: application/json

Example:

{
  "error": {
    "name": "Error",
    "message": "Longitude or latitude parameter missing"
  }
}

HTTP status code 401

Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
  "$schema":"http://json-schema.org/draft-04/schema#",
  "title":"error",
  "description":"Schema for API specified errors.",
  "type":"object",
  "properties":
  {
    "status":
    {
      "type":"integer",
      "description":"original HTTP error code, should be consistent with the response HTTP code",
      "minimum":100,
      "maximum":599
    },
    "type":
    {
      "type":"string",
      "description":"classification of the error type, lower case with underscore eg validation_failure",
      "pattern":"[a-z]+[a-z_]*[a-z]+"
    },
    "message":
    {
      "type":"string",
      "description":"descriptive error message for debugging"
    },
    "moreInfo":
    {
      "type":"string",
      "format":"uri",
      "description":"link to documentation to investigate further and finding support"
    },
    "details":
    {
      "type":"array",
      "description":"list of problems causing this error",
      "items":
      {
        "$schema":"http://json-schema.org/draft-04/schema#",
        "title":"errorDetail",
        "description":"schema for specific error cause",
        "type":"object",
        "properties":
        {
          "field":
          {
            "type":"string",
            "description":"a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
          },
          "type":
          {
            "type":"string",
            "description":"classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
            "pattern":"[a-z]+[a-z_]*[a-z]+"
          },
          "message":
          {
            "type":"string",
            "description":"descriptive error detail message for debugging"
          },
          "moreInfo":
          {
            "type":"string",
            "format":"uri",
            "description":"link to documentation to investigate further and finding support for error detail"
          }
        },
        "required":["type"]
      }
    }
  },
  "required":["status" , "type" ]
}

Example:

{
  "status":401,
  "message":"Authorization: Unauthorized. Bearer TOKEN is invalid",
  "type":"insufficient_credentials",
  "moreInfo":"https://pattern.yaas.io/errortypes.html"
}

HTTP status code 403

Evaluated request scopes in access token are not sufficient and do not match required scopes.

Body

Type: application/json

Schema:

{
  "$schema":"http://json-schema.org/draft-04/schema#",
  "title":"error",
  "description":"Schema for API specified errors.",
  "type":"object",
  "properties":
  {
    "status":
    {
      "type":"integer",
      "description":"original HTTP error code, should be consistent with the response HTTP code",
      "minimum":100,
      "maximum":599
    },
    "type":
    {
      "type":"string",
      "description":"classification of the error type, lower case with underscore eg validation_failure",
      "pattern":"[a-z]+[a-z_]*[a-z]+"
    },
    "message":
    {
      "type":"string",
      "description":"descriptive error message for debugging"
    },
    "moreInfo":
    {
      "type":"string",
      "format":"uri",
      "description":"link to documentation to investigate further and finding support"
    },
    "details":
    {
      "type":"array",
      "description":"list of problems causing this error",
      "items":
      {
        "$schema":"http://json-schema.org/draft-04/schema#",
        "title":"errorDetail",
        "description":"schema for specific error cause",
        "type":"object",
        "properties":
        {
          "field":
          {
            "type":"string",
            "description":"a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
          },
          "type":
          {
            "type":"string",
            "description":"classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
            "pattern":"[a-z]+[a-z_]*[a-z]+"
          },
          "message":
          {
            "type":"string",
            "description":"descriptive error detail message for debugging"
          },
          "moreInfo":
          {
            "type":"string",
            "format":"uri",
            "description":"link to documentation to investigate further and finding support for error detail"
          }
        },
        "required":["type"]
      }
    }
  },
  "required":["status" , "type" ]
}

Example:

{
  "status": 403,
  "message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
  "type": "insufficient_permissions"
}

HTTP status code 500

Internal Server Error

Body

Type: application/json

Example:

{
  "error": {
    "name": "Error",
    "message": "Internal Server Error"
  }
}

/search

Service Usage

Call the /search endpoint with WGS84 coordinates as the long and lat parameters. Set the radius parameter to define the search radius in meters around the location.

The underlying dataset consists of the GeoNames geographical database. It contains cities, lakes, parks, public buildings, and more. The GeoNames geographical database is licensed under CC BY 3.0.

Introduction

To use this tutorial, you must have a valid Bearer access token.

For more information about how to get an access token, see the /token endpoint of the OAuth2 service's API Reference.

All tutorials are designed in a way that you can use them at the same time with the cURL REST client. You can also use the API Console to try out the API.

Request points of interest

You can query the POI service with any location. In this tutorial, you learn how to get points of interest at the center of Berlin.

The coordinates for the center of Berlin in WGS84 format are 52.518611, 13.408333. This means you set the long parameter to 13.408333 and the lat parameter to 52.518611. Set radius=200 to get locations within a 200m radius of this point.

You can quickly visualize the response using any GeoJSON renderer. For example, http://geojson.io or http://geojsonlint.com.

  /search?long=13.408333&lat=52.518611&radius=200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.4081,
          52.5186
        ]
      },
      "properties": {
        "distance": 26.02,
        "name": "Rotes Rathaus",
        "asciiName": "Rotes Rathaus",
        "featureDescription": "administrative facility",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.4083,
          52.5183
        ]
      },
      "properties": {
        "distance": 57.01,
        "name": "Rathaus Berlin",
        "asciiName": "Rathaus Berlin",
        "featureDescription": "administrative facility",
        "countryCode": "DE"
      }
    }
  ]
}

Adjusting the radius to 500m yields a larger result set.

  /search?long=13.408333&lat=52.518611&radius=500

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.4081,
          52.5186
        ]
      },
      "properties": {
        "distance": 26.02,
        "name": "Rotes Rathaus",
        "asciiName": "Rotes Rathaus",
        "featureDescription": "administrative facility",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.4083,
          52.5183
        ]
      },
      "properties": {
        "distance": 57.01,
        "name": "Rathaus Berlin",
        "asciiName": "Rathaus Berlin",
        "featureDescription": "administrative facility",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.40745,
          52.51748
        ]
      },
      "properties": {
        "distance": 229.06,
        "name": "Nikolaiviertel",
        "asciiName": "Nikolaiviertel",
        "featureDescription": "section of populated place",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.40718,
          52.51742
        ]
      },
      "properties": {
        "distance": 252.87,
        "name": "Nikolai Residence Hotel",
        "asciiName": "Nikolai Residence Hotel",
        "featureDescription": "hotel",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.4074,
          52.5168
        ]
      },
      "properties": {
        "distance": 347.2,
        "name": "Nikolaikirche",
        "asciiName": "Nikolaikirche",
        "featureDescription": "church",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.40941,
          52.52082
        ]
      },
      "properties": {
        "distance": 421.53,
        "name": "Berliner Fernsehturm",
        "asciiName": "Berliner Fernsehturm",
        "featureDescription": "tower",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.405,
          52.52
        ]
      },
      "properties": {
        "distance": 449.7,
        "name": "Winters Hotel Berlin Mitte The Wall",
        "asciiName": "Winters Hotel Berlin Mitte The Wall",
        "featureDescription": "hotel",
        "countryCode": "DE"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          13.40489,
          52.52003
        ]
      },
      "properties": {
        "distance": 462.91,
        "name": "Mitte",
        "asciiName": "Mitte",
        "featureDescription": "section of populated place",
        "countryCode": "DE"
      }
    }
  ]
}

You can visualize the GeoJSON object on a map to see the locations of the points of interest. In our example, the points of interest are highlighted by blue markers and the reference point is shown with a blue square.

Send feedback
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Get Help
Use our private help channel. Receive updates over email and contact our specialists directly.
hybris Experts
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.

Overview

API Reference

/search

/search

get /search

Headers

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 403

Body

HTTP status code 500

Body

Service Usage

Introduction

Request points of interest