Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation cleanup

  • Loading branch information...
commit 653571b1e373aea26caba7abe67dd78abc08fd9e 1 parent 9f1b7ba
@coderholic authored
Showing with 71 additions and 101 deletions.
  1. +67 −97 README.md
  2. +4 −4 setup.py
View
164 README.md
@@ -1,112 +1,38 @@
- django-cities -- *Place models and data for Django apps*
-=========================================================
+# django-cities
+### Place models and worldwide place data for Django
-This add-on provides models and commands to import country/region/city data into your database.
-The data is pulled from [GeoNames](http://www.geonames.org/) and contains:
+----
- - localized names
- - geographical codes
- - postal codes
- - geo-coords
- - population
+django-cities provides you with place related models (eg. Country, Region, City) and data (from [GeoNames](http://www.geonames.org/)) that can be used in your django projects.
-Your database must support spatial queries, see [GeoDjango]
-(https://docs.djangoproject.com/en/dev/ref/contrib/gis/) for setup.
+Authored by [Ben Dowling](http://www.coderholic.com), and some great [contributors](https://github.com/coderholic/django-cities/contributors).
-For more information see [this blog post]
-(http://www.coderholic.com/django-cities-countries-regions-cities-and-districts-for-django/).
+----
+### Requirements
- Examples
---------------------------
-Finding all London boroughs:
+Your database must support spatial queries, see the [GeoDjango documentation](https://docs.djangoproject.com/en/dev/ref/contrib/gis/) for details and setup instructions.
-```python
- london = City.objects.filter(country__name='United Kingdom').get(name='London')
- boroughs = District.objects.filter(city=london)
-```
-Nearest city to a given geo-coord (longitude, latitude):
+### Setup
-```python
- City.objects.distance(Point(1, 51)).order_by('distance')[0]
- <City: Dymchurch, Kent, United Kingdom>
-```
+Either clone this repository into your project, or install with ```pip install django-cities```
-5 Nearest cities to London:
+You'll need to add ```cities``` to ```INSTALLED_APPS``` in your projects settings.py file:
```python
- london = City.objects.filter(country__name='United Kingdom').get(name='London')
- nearest = City.objects.distance(london.location).exclude(id=london.id).order_by('distance')[:5]
-```
-
-Get a list of all cities in a state or county:
-
-```python
- City.objects.filter(country__name="United States", region__name="Texas")
- City.objects.filter(country__name="United States", subregion__name="Orange County")
-```
-
-Get all countries in Japanese preferring official names if available, fallback on ASCII names:
-
-```python
- [country.alt_names_ja.get_preferred(default=country.name) for country in Country.objects.all()]
-```
-
-Use alternate names model to get Vancouver in Japanese:
-
-```python
- geo_alt_names[City]['ja'].objects.get_preferred(geo__name='Vancouver', default='Vancouver')
-```
-
-Gather names of Tokyo from all CITIES_LOCALES:
-
-```python
- [name for locale in cities.conf.settings.locales
- for name in geo_alt_names[City][locale].objects.filter(geo__name='Tokyo')]
-```
-
-Get all postal codes for Ontario, Canada (only first 3 letters available due to copyright restrictions):
-
-```python
- postal_codes['CA'].objects.filter(region__name='Ontario')
-```
-
-Get region objects for US postal code:
-
-```python
- Region.objects.filter(postal_codes_US__code='90210')
- [<Region: California, United States>]
- Subregion.objects.filter(postal_codes_US__code='90210')
- [<Subregion: Los Angeles County, California, United States>]
-```
-
- Install
---------------------------
-- Run: `python setup.py install`
-- Add/Merge the following into your *settings.py*:
-
------------------------------------------------------------
-```python
INSTALLED_APPS = (
+ ...
'cities',
)
-LOGGING = {
- 'handlers': {
- 'console':{
- 'level':'DEBUG',
- 'class':'logging.StreamHandler',
- },
- },
- 'loggers': {
- 'cities': {
- 'handlers': ['console'],
- 'level': 'INFO',
- }
- }
-}
+Then run ```./manage.py syncdb``` to create the required database tables, and ```./manage.py cities --import=all``` to import all of the place data. **NOTE:** This can take a long time.
+
+### Configuration
+
+There are various optional configuration options you can set in your ```settings.py```:
+```python
CITIES_FILES = {
# Uncomment below to import all cities with population > 1000 (default is > 5000)
#'city': {
@@ -130,15 +56,59 @@ CITIES_PLUGINS = [
'cities.plugin.postal_code_ca.Plugin', # Canada postal codes need region codes remapped to match geonames
]
```
------------------------------------------------------------
-- Sync your database with the new models: `manage.py syncdb`
-- Populate or update your database: `manage.py cities`
+### Examples
+
+This repostitory contains an example project which lets you browse the place hierarchy. See the ```example``` directory. Below are some small snippets to show you the kind of things that are possible:
+
+Finding all London boroughs:
+
+```python
+# Find the 5 most populated countries in the World
+>>> Country.objects.order_by('-population')[:5]
+[<Country: China>, <Country: India>, <Country: United States>, <Country: Indonesia>, <Country: Brazil>]
+
+# Find what country the .ly TLD belongs to
+>>> Country.objects.get(tld='ly')
+<Country: Libya>
+
+
+# 5 Nearest cities to London
+
+ london = City.objects.filter(country__name='United Kingdom').get(name='London')
+ nearest = City.objects.distance(london.location).exclude(id=london.id).order_by('distance')[:5]
+
+# All cities in a state or county
+
+ City.objects.filter(country__name="United States", region__name="Texas")
+ City.objects.filter(country__name="United States", subregion__name="Orange County")
+
+
+# Get all countries in Japanese preferring official names if available, fallback on ASCII names:
+
+[country.alt_names_ja.get_preferred(default=country.name) for country in Country.objects.all()]
+
+
+# Use alternate names model to get Vancouver in Japanese
+
+ geo_alt_names[City]['ja'].objects.get_preferred(geo__name='Vancouver', default='Vancouver')
+
+
+# Get region objects for US postal code:
+ Region.objects.filter(postal_codes_US__code='90210')
+ [<Region: California, United States>]
+ Subregion.objects.filter(postal_codes_US__code='90210')
+ [<Subregion: Los Angeles County, California, United States>]
+
+```
+
+### Notes
- Notes
---------------------------
The localized names and postal code models/db-tables are created dynamically based on your settings.
+
Some datasets are very large (> 100 MB) and take time to download / import, and there's no progress display.
+
Data will only be downloaded / imported if it is newer than your data, and only matching rows will be overwritten.
+
The cities manage command has options, see --help. Verbosity is controlled through LOGGING.
View
8 setup.py
@@ -11,10 +11,10 @@ def read(fname):
setup(
name='django-cities',
version='0.2',
- description='Place models and data for Django apps',
- author='Dan Carter (original by Ben Dowling)',
- author_email='carterd@gmail.com',
- url='https://github.com/Kometes/django-cities',
+ description='Place models and worldwide place data for Django'
+ author='Ben Dowling',
+ author_email='ben.m.dowling@gmail.com',
+ url='https://github.com/coderholic/django-cities',
packages=find_packages(),
include_package_data=True,
zip_safe=False,
Please sign in to comment.
Something went wrong with that request. Please try again.