# 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/28/22/6dafcad37f3b4f86289275086719fea515549b3c66c7409272481a0a0ee1/django_global_places-0.8.4.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.4",
"project_urls": {
"Homepage": "https://github.com/lucacitta/Django-GlobalPlaces"
},
"split_keywords": [
"django",
"global",
"places"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78890bd85c875fa4807df31776ee7bee61065cd2f528098fd482610fd579043f",
"md5": "e009fa0dc713aad5438b6d5d6d498c09",
"sha256": "70ce9e43bdae0674a18c5fb6faa0a5eb759f80caacce3c8c01a3784ae3d90560"
},
"downloads": -1,
"filename": "django_global_places-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e009fa0dc713aad5438b6d5d6d498c09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15598,
"upload_time": "2024-05-06T09:19:57",
"upload_time_iso_8601": "2024-05-06T09:19:57.878548Z",
"url": "https://files.pythonhosted.org/packages/78/89/0bd85c875fa4807df31776ee7bee61065cd2f528098fd482610fd579043f/django_global_places-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28226dafcad37f3b4f86289275086719fea515549b3c66c7409272481a0a0ee1",
"md5": "8deaa5c3242e6f94b84033c487a732c9",
"sha256": "fde12c640768decfa644651ed354e6b48d9e483d8735f2879b0c3d90fb17f1ce"
},
"downloads": -1,
"filename": "django_global_places-0.8.4.tar.gz",
"has_sig": false,
"md5_digest": "8deaa5c3242e6f94b84033c487a732c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11287,
"upload_time": "2024-05-06T09:20:01",
"upload_time_iso_8601": "2024-05-06T09:20:01.815056Z",
"url": "https://files.pythonhosted.org/packages/28/22/6dafcad37f3b4f86289275086719fea515549b3c66c7409272481a0a0ee1/django_global_places-0.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 09:20:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucacitta",
"github_project": "Django-GlobalPlaces",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-global-places"
}
JSON
