https://github.com/freekbes/postal-codes-gazetteer

A Gazetteer for looking up the location of postal codes, developed for usage with Grafana's geomaps
https://github.com/freekbes/postal-codes-gazetteer

gazetteer geomapping grafana grafana-geomap postal-codes

Last synced: 1 day ago
JSON representation

A Gazetteer for looking up the location of postal codes, developed for usage with Grafana's geomaps

• Host: GitHub
• URL: https://github.com/freekbes/postal-codes-gazetteer
• Owner: FreekBes
• License: cc-by-4.0
• Created: 2025-02-11T19:12:59.000Z (3 days ago)
• Default Branch: main
• Last Pushed: 2025-02-11T19:20:11.000Z (3 days ago)
• Last Synced: 2025-02-11T20:27:27.269Z (3 days ago)
• Topics: gazetteer, geomapping, grafana, grafana-geomap, postal-codes
• Language: Python
• Homepage:
• Size: 8.79 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES
  • License: LICENSE

Awesome Lists containing this project

README

        
# Gazetteer for Postal Codes in Grafana

This is a Grafana plugin that provides a gazetteer for postal codes.

---

## Creating the Gazetteer dataset

### Data source

Before beginning, download the postal codes data from [Opendatasoft](https://data.opendatasoft.com/explore/dataset/geonames-postal-code@public/export/) in GeoJSON format.

### Converting the data source for usage with Grafana

1. Set up a virtual environment:

```bash

python3 -m venv venv

```

2. Activate the virtual environment:

```bash

source venv/bin/activate

```

3. Install the required packages:

```bash

pip install -r requirements.txt

```

4. Run the conversion script:

```bash

python convert.py --input  --output 

```

---

## How to use in Grafana

Upload the generated *postal-codes.json* output file to the Grafana *public/gazetteer* folder (in my case `/usr/share/grafana/public/gazetteer`).

Then, when creating a new panel, select the Geomap visualization.

Set the Location Mode to Lookup, specify the Lookup field to a combination of a country code and a postal code in the following format: `CN-POSTALCODE` (e.g. `DE-12345` or `US-12345`). Specific postal codes for buildings or addresses will not work, you will need to truncate them to use only the area code. You will need to figure out yourself how to do this.

Set the Gazetteer to the uploaded JSON file by pasting the URL to it into the input field and pressing enter.

> Example URL: *http://grafana.example.com/public/gazetteer/postal-codes.json*

## Warning

The data might be incomplete. In this case, do not reach out to me, instead complain to Opendatasoft.

Also, the dataset will be approximately 170MB in size. Loading a Geomap with this dataset will use a lot of network bandwidth and RAM on your device. Be aware of this before using it.