# Django-GlobalPlaces
Plug and play configurations and data for countries, states and cities from all over the globe.
## Requirements
- Django >= 3.8 *
- Python >= 3.8 *
- Django Rest Framework >= 3.13 *
- This requirement is only necessary if you are using the provided REST endpoints.
- django-filter >= 23.0 *
- This requirement is only necessary if you are using the provided REST endpoints.
(*) Not tested with earlier versions.
## Quick Setup
Install package
pip install django-global-places
Add `django_global_places` app to INSTALLED_APPS in your django settings.py:
```python
INSTALLED_APPS = (
...,
"django.contrib.staticfiles",
'django_global_places'
'rest_framework', # required only if using the provided REST endpoints
...,
)
```
(Optional) Include viewset routes
```python
from django_global_places.urls import router as django_global_places_router
your_router.registry.extend(django_global_places_router.registry)
```
### Explanation
This library handles the configuration and creation of `Countries`, `States`, and `Cities`.
After installation, you need to specify three parameters in your `settings.py` file:
- `INCLUDE_LOCATION`: Enables the creation of the models.
- `LOCATION_SCOPE`: Determines the scope of models required ('countries', 'states', or 'cities').
- `INCLUDE_EXPANDED_COUNTRY`: Incorporates additional fields into the Country model.
Example:
GLOBAL_PLACES = {
"INCLUDE_LOCATION": True,
"LOCATION_SCOPE": "state",
"INCLUDE_EXPANDED_COUNTRY": False,
}
Once these variables are configured, your next steps are to run `makemigrations` and `migrate`.
To **populate** the newly created models, you should execute a Django command. This command will create all the necessary objects and update them if they already exist.
python manage.py populate_global_places
### Rest endpoints
Three viewsets are included, one for each model: `Country`, `State`, and `City`. Each viewset features:
A list view displaying a summary of the objects.
A detail view presenting comprehensive information about each object.
- CountryViewSet:
- url: global-places/countries
- search fields: `name` and `iso3`
- ordering fields: `id`, `name` and `iso3`
- StateViewSet:
- url: global-places/states
- search fields: `name` and `state_code`
- ordering fields: `id`, `name` and `state_code`
- filtering fields: `country`
- CityViewSet:
- url: global-places/cities
- search fields: `name`
- ordering fields: `id` and `name`
- filtering fields: `state`, `state__country`
Full examples [here](https://www.postman.com/restless-zodiac-765340/workspace/django-globalplaces/collection/18007906-46245b57-0675-4bfb-ae41-c71ee6f6f6f5?action=share&creator=18007906) in Postman collection.
### Acknowledgements
Special thanks to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) for providing the JSON files used for populating the data.
## Contributing
- [Luca Cittá Giordano](https://www.linkedin.com/in/lucacittagiordano/)
- [Matias Girardi](https://www.linkedin.com/in/matiasgirardi)
Maintained and developed by [Linkchar Software Development](https://linkchar.com/).
Raw data
{
"_id": null,
"home_page": "https://github.com/lucacitta/Django-GlobalPlaces",
"name": "django-global-places",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django global places",
"author": "lucacitta",
"author_email": "lucacitta.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2f/51/c15890763e967cce9d777b745444b9f109fa32edc98ab908be6269110fa1/django_global_places-0.8.7.tar.gz",
"platform": null,
"description": "\r\n# Django-GlobalPlaces\r\nPlug and play configurations and data for countries, states and cities from all over the globe.\r\n\r\n## Requirements\r\n- Django >= 3.8 *\r\n- Python >= 3.8 *\r\n- Django Rest Framework >= 3.13 *\r\n\t- This requirement is only necessary if you are using the provided REST endpoints.\r\n- django-filter >= 23.0 *\r\n\t- This requirement is only necessary if you are using the provided REST endpoints.\r\n\r\n\r\n(*) Not tested with earlier versions.\r\n\r\n## Quick Setup\r\n\r\nInstall package\r\n\r\n pip install django-global-places\r\n \r\nAdd `django_global_places` app to INSTALLED_APPS in your django settings.py:\r\n\r\n```python\r\nINSTALLED_APPS = (\r\n ...,\r\n \"django.contrib.staticfiles\",\r\n 'django_global_places'\r\n 'rest_framework', # required only if using the provided REST endpoints\r\n ...,\r\n)\r\n```\r\n \r\n(Optional) Include viewset routes\r\n\r\n```python\r\nfrom django_global_places.urls import router as django_global_places_router\r\nyour_router.registry.extend(django_global_places_router.registry)\r\n```\r\n \r\n\r\n### Explanation\r\n\r\n\r\nThis library handles the configuration and creation of `Countries`, `States`, and `Cities`.\r\n\r\nAfter installation, you need to specify three parameters in your `settings.py` file:\r\n\r\n- `INCLUDE_LOCATION`: Enables the creation of the models.\r\n- `LOCATION_SCOPE`: Determines the scope of models required ('countries', 'states', or 'cities').\r\n- `INCLUDE_EXPANDED_COUNTRY`: Incorporates additional fields into the Country model.\r\n\r\nExample:\r\n\r\n GLOBAL_PLACES = {\r\n\t \"INCLUDE_LOCATION\": True,\r\n\t \"LOCATION_SCOPE\": \"state\",\r\n\t \"INCLUDE_EXPANDED_COUNTRY\": False,\r\n }\r\n\r\n\r\nOnce these variables are configured, your next steps are to run `makemigrations` and `migrate`.\r\n\r\nTo **populate** the newly created models, you should execute a Django command. This command will create all the necessary objects and update them if they already exist.\r\n\r\n python manage.py populate_global_places\r\n\r\n### Rest endpoints\r\n\r\nThree viewsets are included, one for each model: `Country`, `State`, and `City`. Each viewset features:\r\n\r\nA list view displaying a summary of the objects.\r\nA detail view presenting comprehensive information about each object.\r\n\r\n- CountryViewSet:\r\n\t- url: global-places/countries\r\n\t- search fields: `name` and `iso3`\r\n\t- ordering fields: `id`, `name` and `iso3`\r\n\r\n- StateViewSet:\r\n\t- url: global-places/states\r\n\t- search fields: `name` and `state_code`\r\n\t- ordering fields: `id`, `name` and `state_code`\r\n\t- filtering fields: `country`\r\n\r\n- CityViewSet:\r\n\t- url: global-places/cities\r\n\t- search fields: `name`\r\n\t- ordering fields: `id` and `name`\r\n\t- filtering fields: `state`, `state__country`\r\n\r\nFull examples [here](https://www.postman.com/restless-zodiac-765340/workspace/django-globalplaces/collection/18007906-46245b57-0675-4bfb-ae41-c71ee6f6f6f5?action=share&creator=18007906) in Postman collection.\r\n\r\n### Acknowledgements\r\n\r\nSpecial thanks to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) for providing the JSON files used for populating the data.\r\n\r\n## Contributing\r\n\r\n- [Luca Citt\u00e1 Giordano](https://www.linkedin.com/in/lucacittagiordano/)\r\n \r\n- [Matias Girardi](https://www.linkedin.com/in/matiasgirardi)\r\n\r\nMaintained and developed by [Linkchar Software Development](https://linkchar.com/).\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django Global Places is a simple Django app to provide a model for global places.",
"version": "0.8.7",
"project_urls": {
"Homepage": "https://github.com/lucacitta/Django-GlobalPlaces"
},
"split_keywords": [
"django",
"global",
"places"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4387fbe39aae1725aa08e568d3a0f5ca682c5dc834a200212e617f004b429c0d",
"md5": "d2ca75359740f931c4b1c61e34fc87a4",
"sha256": "6f40ee13e01f8e705ec54130feb9d1a7d71d9ca7dcdccf10124406849f05ab26"
},
"downloads": -1,
"filename": "django_global_places-0.8.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2ca75359740f931c4b1c61e34fc87a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16383,
"upload_time": "2024-05-27T12:28:05",
"upload_time_iso_8601": "2024-05-27T12:28:05.118352Z",
"url": "https://files.pythonhosted.org/packages/43/87/fbe39aae1725aa08e568d3a0f5ca682c5dc834a200212e617f004b429c0d/django_global_places-0.8.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f51c15890763e967cce9d777b745444b9f109fa32edc98ab908be6269110fa1",
"md5": "dadb6ac20bd0534a3b4904d9f049d7d4",
"sha256": "3b7d08011f6f4a26235a8aff7b069fe1948d287976fbd066c9e38f75b74f42cf"
},
"downloads": -1,
"filename": "django_global_places-0.8.7.tar.gz",
"has_sig": false,
"md5_digest": "dadb6ac20bd0534a3b4904d9f049d7d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11949,
"upload_time": "2024-05-27T12:28:08",
"upload_time_iso_8601": "2024-05-27T12:28:08.257386Z",
"url": "https://files.pythonhosted.org/packages/2f/51/c15890763e967cce9d777b745444b9f109fa32edc98ab908be6269110fa1/django_global_places-0.8.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 12:28:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucacitta",
"github_project": "Django-GlobalPlaces",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-global-places"
}
JSON
