> For the complete documentation index, see [llms.txt](https://floriankuwala.gitbook.io/kuwala/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://floriankuwala.gitbook.io/kuwala/quick-start/local-deployment/popularity-data.md).

# Popularity Data

## Google POIs

Nearly every customer facing business and POI is represented on Google. Apart from data on reviews and categorization there is also aggregated and anonymized movement data available represented as a popularity index for a location.

The popularity is a relative score per location between 0 and 100. A score of 100 for a given hour represents the time of the respective place with its highest number of visitors during the week. Each value is marked with a timestamp which makes it suitable for time series analysis.

For places with a very high number of average visitors there is also the live popularity for the current hour available. This score can also be over 100 if the number of visitors is extraordinarily high.

[![Popularity Graph](https://github.com/kuwala-io/kuwala/raw/master/docs/images/google_poi_popularity_graph.png)](https://github.com/kuwala-io/kuwala/blob/master/docs/images/google_poi_popularity_graph.png)

#### Features

* Name
* PlaceID (from Google)
* Location (latitude and longitude)
* H3 index
* Address
* Timezone
* Categories
* Temporarily closed tag
* Permanently closed tag
* Inside of tag (e.g., inside an airport or shopping mall)
* Contact (phone and website)
* Opening hours (also considers public holidays)
* Rating (stars and number of reviews)
* Price level
* Popularity
* Waiting time
* Spending time

### Prerequisites

Installed version of *Python3*.

### Setup

Install pip packages.

```
pip install -r requirements.txt
```

In order to not run into rate limits we recommend using a proxy (e.g., [Tor](https://www.torproject.org/download/)). Specify the address of the running proxy in the `config/env/.env.local` through the `PROXY_ADDRESS` variable.

### Usage

Run the app locally (convenience script available under `scripts`).

```
python app.py local
```

#### API Calls

For performance reasons the amount of queries or ids that can be sent with one query is limited to 100.

**Get encoded placeID and location for search string**

Request Method: **GET**\
URL: `/search`\
Request Body (**required**): Array of search strings<br>

*Example*: `localhost:3003/search`\
Request Body:

```
    [
        "Eiffel Tower, Avenue Anatole France 5,  75007 Paris",
        "Piccadilly Circus station, London",
        "Starbucks, Grunerstraße 20, 10179 Berlin"
    ]
```

**Get POI information based on encoded placeID**

The encoded placeIDs must be retrieved over the `/search` call.

Request Method: **GET**\
URL: `/poi-information`\
Request Body (**required**): Array of encoded placeIDs<br>

*Example*: `localhost:3003/poi-information`\
Request Body:

```
    [
        "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
        "0x487604d3e05e54bd:0xa3f4c9ef40a075c3",
        "0x47a84e22134bcf99:0x5541176eb2ed92f7"
    ]
```

**Get current popularity based on encoded placeID**

The encoded placeID must be retrieved over the `/search` call.

Request Method: **GET**\
URL: `/popularity`\
Request Body (**required**): Array of encoded placeIDs<br>

*Example*: `localhost:3003/popularity`\
Request Body:

```
    [
        "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
        "0x487604d3e05e54bd:0xa3f4c9ef40a075c3",
        "0x47a84e22134bcf99:0x5541176eb2ed92f7"
    ]
```

#### License

We are not responsible for nor do we take any responsibility for legal claims that might arise. Use at your own risk.