ncdanhvn/vn-provinces-api

Public API for getting Vietnam geographical data likes regions, provinces, districts, wards and some related administration information

Vietnam Provinces API

VN Provinces API is an open API that provides information about administrative units in Vietnam across four levels:

• Region
• Province
• District
• Ward

For more information about API usecases, documentation, please visit links below:

• Homepage
• Documentation

Tech Stack

Server: Django, Rest Framework

Databases: MySQL

Client: Html, Vanilla CSS, VueJS, Vuetify

Documentation: OpenAPI, drf-spectacular

Contributing

Contributions are always welcome!

Please fork the repo then start pull requests.

Installation

• Firstly clone this repository

  git clone https://github.com/ncdanhvn/vn-provinces-api.git
  cd vn-provinces-api

• This project uses pipenv to manage virtual environment. Let's install pipenv first, then install project dependencies.

  pip install pipenv 
  pipenv install

• To run API local on your machine, you need a SQL server. Download and install MySQL here

• After installing MySQL server, you will have a root user with password. Let's enter these information in development settings file at this address: province > settings > dev.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'province',
        'HOST': 'localhost',
        'USER': 'YOUR_USERNAME',
        'PASSWORD': 'YOUR_PASSWORD'
    }
}

• The last step to setup our database is to create province database on the server which we've just installed. Open mysql shell and run create database command.

  CREATE DATABASE province;

• Congratulation now everything set and we are ready to run API on our machine

  pipenv shell
  python manage.py migrate
  python manage.py runserver

• Checkout the homepage of API at default url: http://127.0.0.1:8000/

• At this point, everything should work, but if you visit the api endpoint like http://127.0.0.1:8000/api/provinces, the response results would be empty, since there is nothing on our database. So let's populate database with some demo data.

  python manage.py seed_test_db

Running Tests

Repository already has all tests to test endpoint behaviours, there are total 9 tests for 9 endpoints. To run tests, please do following steps:

First install necessary development packages:

  pipenv install --dev

Then run tests:

  pytest

License

MIT