Using the Rest API (Beta)

Introduction

The Kuwala API provides rich data about places such as type and popularity.

See here the complete documentation on Postman
View a Tutorial Video on how to use Postman for setting up your first call

Authentication

Each request needs to be authorized by providing an API-key in the authorization header. Simply add the key 'Authorization' to your request headers and place your API-key as the value. (E.g., {'Authorization': '7adsfuver7ivyxjaiw337ewr8'})

Rate Limits

For now each user has a limit of 1,000 requests and a total of 1 GB of transferred data.AUTHORIZATIONAPI KeyKey<key>Value{{AUTH_TOKEN}}

Places

These endpoints can be used to fetch data about individual places.

The history property shows for a given year the POI versions. If the POI changed the respective year has at least two entries (e.g., a café turned into a restaurant).AUTHORIZATIONAPI KeyThis folder is using API Key from collectionKuwala APIGET

Get Places By Categoryhttp://api.kuwala.io/places/category/beauty?country=de&city=berlin

Each place belongs to one or more categories which they can be filtered by. This requests returns all places belonging to a given category in a city.

We support the following 27 categories:

airport, apartment, artCulture, automobile, beauty, cafe, delivery, drinks, education, entertainment, fastFood, fitness, government, groceries, medical, misc, office, park, publicService, publicTransportation, religiousBuilding, restaurant, service, shopping, socialService, tourism, wholesaler

The places can additionally be filtered by country or city. We generally support all cities with more than 100k inhabitants. For a complete list of all cities please reach out to hello@kuwala.io.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMScountrydecityberlin Example RequestAll places belonging to category beauty in Berlin, Germany

curl --location --request GET 'http://api.kuwala.io/places/category/beauty?country=de&city=berlin'

Example Response200 OKBodyHeader(8)View More

{
  "status": 200,
  "message": "Fetched all places belonging to category beauty in Berlin, Germany",
  "numberOfResults": 1048,
  "data": [
    {
      "name": "Salon Sabine",
      "location": {
        "lat": 52.4992743,
        "lng": 13.4642434
      },

GET

Get Places In A Specific Areahttp://api.kuwala.io/places/area/circle?lat=52.5110724&lng=13.3900182&radius=1000&category=beauty

Places can be fetched for a certain area having the shape of a circle. The center of the circle is provided by latitude and longitude and the radius sets the maximum distance until which places will be fetched. The category filter is optional.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMSlat52.5110724lng13.3900182radius1000categorybeauty Example RequestPlaces belonging to category beauty in a given area

curl --location --request GET 'http://api.kuwala.io/places/area/circle?lat=52.5110724&lng=13.3900182&radius=1000&category=beauty'

Example Response200 OKBodyHeader(8)View More

{
  "status": 200,
  "message": "Fetched all places belonging to category beauty at [52.5110724;13.3900182] with a radius of 1000 m",
  "numberOfResults": 9,
  "data": [
    {
      "name": "JeanLuc Paris",
      "location": {
        "lat": 52.5183544,
        "lng": 13.3883965
      },

Popularities

These endpoints provide aggregated popularities which can be filtered by different criterea.

The popularity is provided per hour and is index between 0 and 100. The popularity is relative to the highest popularity of the respective POI, e.g., a score of 80 indicates 80% of the maximum popularity the POI has in a week.AUTHORIZATIONAPI KeyThis folder is using API Key from collectionKuwala API

Average

The average popularity for each day and each hour is based on historic data. They are currently calculated on a yearly basis.AUTHORIZATIONAPI KeyThis folder is using API Key from collectionKuwala APIGET

Get Average Popularities By Categoryhttp://api.kuwala.io/popularities/category/shopping?country=de&city=berlin

All places are filtered by category and then the average popularity is calculated. Places can be additionally filtered by country or city.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMScountrydecityberlin Example RequestAverage popularities for category shopping in Berlin, Germany

curl --location --request GET 'http://api.kuwala.io/popularities/category/shopping?country=de&city=berlin'

Example Response200 OKBodyHeader(8)View More

{
  "status": 200,
  "message": "Fetched popularities for category shopping in Berlin, Germany",
  "data": [
    {
      "mon": {
        "average": 19.37201411509229,
        "byHour": [
          0.32301845819761127,
          0.253528773072747,
          0.1997828447339848,

GET

Get Average Popularities In A Specific Areahttp://api.kuwala.io/popularities/area/circle?lat=52.5110724&lng=13.3900182&radius=1500&category=shopping

Returns the average popularity of all places in a specific area. The category filter is optional.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMSlat52.5110724lng13.3900182radius1500categoryshopping Example RequestAverage popularities of category shopping in a given area

curl --location --request GET 'http://api.kuwala.io/popularities/area/circle?lat=52.5110724&lng=13.3900182&radius=1500&category=shopping'

Example Response200 OKBodyHeader(8)View More

{
  "status": 200,
  "message": "Fetched popularities belonging to category shopping at [52.5110724;13.3900182] with a radius of 1500 m",
  "data": [
    {
      "mon": {
        "average": 17.7842039800995,
        "byHour": [
          0.2537313432835821,
          0.05970149253731343,
          0.05970149253731343,

Live

The popularities of relevant places are updated hourly. These endpoints return the live popularities rolling for the last 7 days.

It is possible that live popularities have a score above 100 when the live popularity is higher than the maximum average popularity.AUTHORIZATIONAPI KeyThis folder is using API Key from collectionKuwala APIGET

Get Live Popularities By Categoryhttp://api.kuwala.io/popularities/live/category/drinks?country=de&city=berlin

This call returns the live popularities filtered by category rolling for the past 7 days. Places can be additionally filtered by country or city.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMScountrydecityberlin Example RequestLive popularities for category drinks in Berlin, Germany

curl --location --request GET 'http://api.kuwala.io/popularities/live/category/drinks?country=de&city=berlin'

Example Response200 OKBodyHeader(8)View More

{
  "status": 200,
  "message": "Fetched live popularities for category drinks in Berlin, Germany",
  "data": [
    {
      "mon": {
        "average": 13.409633757961783,
        "byHour": [
          4.634554140127388,
          2.9745222929936306,
          2.037420382165605,

GET

Get Live Popularities In A Specific Areahttp://api.kuwala.io/popularities/live/area/circle?lat=52.5110724&lng=13.3900182&radius=3000&category=drinks

This call returns the live popularities in a given area rolling for the past 7 days. The category filter is optional.AUTHORIZATIONAPI KeyThis request is using API Key from collectionKuwala APIPARAMSlat52.5110724lng13.3900182radius3000categorydrinks

PreviousQuick Start NextLocal Deployment

Last updated 2 years ago