https://github.com/benmaier/django-rkigeonameapi

An API to make relevant queries to an edited Geoname-DB instance.
https://github.com/benmaier/django-rkigeonameapi

Last synced: 2 months ago
JSON representation

An API to make relevant queries to an edited Geoname-DB instance.

• Host: GitHub
• URL: https://github.com/benmaier/django-rkigeonameapi
• Owner: benmaier
• License: mit
• Created: 2019-10-29T11:40:49.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2020-08-31T14:25:48.000Z (almost 5 years ago)
• Last Synced: 2024-10-11T11:06:54.080Z (8 months ago)
• Language: Python
• Size: 41 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# RKI-GeonameAPI

Django-webapp for easy access to a hierarchical geo-location database.

## License

This project is published under the MIT license. It uses the [geoname-data](http://www.geonames.org/) which is licensed under a [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).

## Install and Deployment

Only tested with Python 3.7 and Django 2.2. Make sure you installed the modified version of the [Geoname-DB](https://github.com/benmaier/GeoNames-MySQL-DataImport) beforehand. This app expects an instance of MySQL 8.0. 

Clone this repository.

    git clone [email protected]:benmaier/django-rkigeonameapi.git

Then install with pip

    pip install ./django-rkigeonameapi

### Project settings

Add `rest_framework` and `rkigeonameapi` to your `INSTALLED_APPS` setting like this

```python

INSTALLED_APPS = [

    ...

    'rkigeonameapi',

    'rest_framework',

]

```

You can also add some settings for the rest framework. Here are the ones we typically use:

```python

REST_FRAMEWORK = {

    'DEFAULT_PERMISSION_CLASSES': [

        'rest_framework.permissions.IsAuthenticated',

    ],

    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',

    'PAGE_SIZE': 10,

    'DEFAULT_RENDERER_CLASSES': (

        'rest_framework.renderers.JSONRenderer',

        # The following is used to avoid time-outs in the browsable API

        # (since the automatically generated forms will try to load

        # all geonames in HTML-selects.)

        'rkigeonameapi.renderers.BrowsableAPIRendererWithoutForms',

    ),

}

```

Add the urls to your `projects/urls.py`

```python

urlpatterns += [

    path('rkigeonameapi/', include('rkigeonameapi.urls')),

]

```

In your project, you now need to perform a migration to construct the necessary tables in the database. Please continue reading before actually performing the migration.

### Database

Make sure you installed the modified version of the [Geoname-DB](https://github.com/benmaier/GeoNames-MySQL-DataImport) beforehand. This app expects an instance of MySQL 8.0. Your user/database should have the following settings:

```sql

CREATE SCHEMA `your_db_name` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci ;

CREATE USER 'your_db_user'@'your_host_name' IDENTIFIED BY 'REPLACETHISWITHTHERIGHTPASSWORD';

GRANT ALL PRIVILEGES ON your_db_name.* TO 'your_db_user'@'your_host_name';

GRANT SELECT ON geonames.* TO 'your_db_user'@'your_host_name';

```

For development, you can just use the host `localhost`.

Given these settings, create a mysql-connection file `your/path/to/db.cnf`

```config

[client]

host = your_host_name

port = 3306

user = your_db_user

password = REPLACETHISWITHTHERIGHTPASSWORD

database = your_db_name

default-character-set = utf8mb4

```

Now, do the necessary migrations. In your **project** directory:

    python manage.py migrate

The necessary tables in your `your_db_name`-database should've been created. This means we can migrate the necessary data from the original `geonames`-database.

To this end, navigate back to your local clone of this repository

    cd /path/to/django-rkigeonameapi

And generate the sql migration file `mymigration.sql` with an optional language-code argument.

    python make_geonamemigration_sql.py your/path/to/db.cnf mymigration.sql -l de

Note that this project renames the `name` property of all locations to contain their most common German name by default. If you **don't** want this

you should can specify another language using the corresponding ISO-ALPHA2 code. In case you just want to keep the english name, use `-l en` or 

something nonsensical like `-l XXXXX` 

(the script automatically uses the English name for any

location for which it cannot find a name in the demanded language).

Afterwards, migrate your tables with

    /path/to/your/bin/mysql --defaults-file=your/path/to/db.cnf -v < mymigration.sql

## Logic

The Geoname-Database is an open-source dataset containing an exhaustive list of places on earth.

The database contains information about a variety of properties and relationships of these places

such as alternative names in multiple languages, positional data, and hierarchical relationships

(e.g. to which country oder administrative division a place belongs).

This project provides a simple interface to this database which allows a user to easily

retrieve data and to edit hierarchical relationships.

### Geonames

A Geoname is a main geographical entity. It could be a populated place, a country or something else.

#### API endpoints

Admin: http://localhost:8000/admin/rkigeonameapi/api/geoname/ 

REST:

| Action | Link | Description |

| ------ | ---- | ----------- |

| list/create | http://localhost:8000/rkigeonameapi/api/geoname/ | Show a JSON list of all Geoname-objects and add an entry |

| view/update | http://localhost:8000/rkigeonameapi/api/geoname/INTID | Show a single Geoname-object associated with the primary key as JSON |

| search | http://localhost:8000/rkigeonameapi/api/geonamesearch/SEARCHSTRING | Show all Geoname-objects whose `name` and `englishname` contain the `SEARCHSTRING` |

| exhaustive search | http://localhost:8000/rkigeonameapi/api/geonameexhaustivesearch/SEARCHSTRING | Show all Geoname-objects whose `alternatenames` or `englishname` start with the `SEARCHSTRING` |

| search by feature code | http://localhost:8000/rkigeonameapi/api/geonamesearch/SEARCHSTRING?fcode=ADM1,PCLI | As above, but only show geonames whose feature code is in the list of feature codes provided in the URL |

| exhaustive search by feature code| http://localhost:8000/rkigeonameapi/api/geonameexhaustivesearch/SEARCHSTRING?fcode=ADM1,PCLI | See definitions above |

A Geoname can always contain multiple children (think of a US state containing cities). Here's how you control those hierarchical relationships

Admin: http://localhost:8000/admin/rkigeonameapi/api/hierarchy/

REST:

| Action | Link | Description |

| ------ | ---- | ----------- |

| update | http://localhost:8000/rkigeonameapi/api/geonamechildren/INTID | Show (`GET`) and update (`PATCH`) the children of a single Geoname-object |

| view specific | http://localhost:8000/rkigeonameapi/api/geonamefcodechildren/INTID?fcode=ADM1,ADM2 | Show all children of a single Geoname-object that are associated with any of the specified feature codes |

### Feature codes

Each Geoname is associated with a feature code. Here are the most relevant ones with explanations

Admin: http://localhost:8000/admin/rkigeonameapi/api/featurecode

REST: 

* list/create: http://localhost:8000/rkigeonameapi/api/featurecode

* view/update: http://localhost:8000/rkigeonameapi/api/featurecode/STRINGID

#### Continents and regions

These are objectes that usually contain multiple countries

fcode | name | description

----- | ---- | -----------

CONT | continent | continent: Europe, Africa, Asia, North America, South America, Oceania, Antarctica

RGN | region | an area distinguished by one or more observable physical or cultural characteristics

A region might also contain other places but this won't be of interest in this application. 

#### Countries

These are used as synonyms for countries

| fcode | name 

| ----- | ---- 

| PCLI | independent political entity

| TERR | territory

| PCLD | dependent political entity

#### Places

These are used as synonyms for cities/villages/places that are neither countries nor regions nor administrative sections.

| fcode | name | description

| ----- | ---- | -----------

| PPLC | capital of a political entity | |

| PPL | populated place | a city, town, village, or other agglomeration of buildings where people live and work

| PPLA | seat of a first-order administrative division | seat of a first-order administrative division (PPLC takes precedence over PPLA) 

| PPLX | section of populated place | |

#### Administrative divisions

These are hierarchically decreasing administrative divisions of a country

| fcode | name | description

| ----- | ---- | -----------

| ADM1| first-order administrative division | a primary administrative division of a country, such as a state in the United States

| ADM2| second-order administrative division | a subdivision of a first-order administrative division

| ADM3| third-order administrative division | a subdivision of a second-order administrative division

| ADM4| fourth-order administrative division | a subdivision of a third-order administrative division

| ADM5| fifth-order administrative division | a subdivision of a fourth-order administrative division

### Regions

Custom regions are shortcuts for improved handling/grouping of countries.

Admin: http://localhost:8000/admin/rkigeonameapi/api/region/

REST:

* list/create: http://localhost:8000/rkigeonameapi/api/region/

* view/update: http://localhost:8000/rkigeonameapi/api/region/STRINGID

You may want to alter a region's children countries by using

* http://localhost:8000/rkigeonameapi/api/regioncountries/STRINGID

### Countries

The database holds specific info about countries.

Admin: http://localhost:8000/admin/rkigeonameapi/api/country/

REST:

* list/create: http://localhost:8000/rkigeonameapi/api/country/

* view/update: http://localhost:8000/rkigeonameapi/api/country/STRINGID

### Continents

The database holds specific info about continents.

Admin: http://localhost:8000/admin/rkigeonameapi/api/continent/

REST:

* list/create: http://localhost:8000/rkigeonameapi/api/continent/

* view/update: http://localhost:8000/rkigeonameapi/api/continent/STRINGID