# 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](https://documenter.getpostman.com/view/12536265/TVKD1cdc)
* [View a Tutorial Video](https://floriankuwala.gitbook.io/kuwala/tutorials/using-the-api-with-postman) 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\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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)GET
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 .AUTHORIZATIONAPI KeyThis request is using API Key from collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMScountrydecityberlin\
\
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMSlat52.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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)GET
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMScountrydecityberlin\
\
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMSlat52.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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)GET
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMScountrydecityberlin\
\
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 collection[Kuwala API](https://documenter.getpostman.com/view/12536265/TVKD1cdc#auth-info-3ee3513d-b810-45b5-9321-5a5d1ac66090)PARAMSlat52.5110724lng13.3900182radius3000categorydrinks
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://floriankuwala.gitbook.io/kuwala/quick-start/using-the-rest-api-beta.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.