Skip to content
Geography for civic databases.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Manage political geographic and spatial data, the POLITICO way.

Creates a complete set of political geometries as topojson for export to AWS S3 or to interact with in your database.

Read the docs.


  1. Install the app.
$ pip install politico-civic-geography
  1. Add the app to your Django project and configure settings.
    # ...

# geography settings

GEOGRAPHY_AWS_REGION = "us-east-1" # default
GEOGRAPHY_AWS_S3_UPLOAD_ROOT = "elections" # default
GEOGRAPHY_AWS_ACL = "public-read" # default
GEOGRAPHY_AWS_CACHE_HEADER = "max-age=3600" # default
GEOGRAPHY_API_AUTHENTICATION_CLASS = "rest_framework.authentication.BasicAuthentication" # default
GEOGRAPHY_API_PERMISSION_CLASS = "rest_framework.permissions.IsAdminUser" # default
GEOGRAPHY_API_PAGINATION_CLASS = "geography.pagination.ResultsPagination" # default
  1. Migrate the database.
$ python migrate geography

Bootstrapping your database

civic-geography can bootstrap a database of US national, state and county data for you from U.S. Census cartographic boundary files, creating simplified topojson geography. Just run it!

$ python bootstrap_geography

Use the --help flag to see additional options.

Note: In order to create simplified geography, you must have topojson installed and available via command line on your machine. You can install it via npm.

$ npm install -g topojson

Publishing geography to S3

You can publish your geometries as topojson to an S3 bucket with this command. Give it a state FIPS code to bake out the geometry for that state, or use :code:00 to bake all states.

$ python bake_geography 00


Running a development server

Move into the example directory, install dependencies and run the development server with pipenv.

$ cd example
$ pipenv install
$ pipenv run python runserver
Setting up a PostgreSQL database
  1. Run the make command to setup a fresh database.
$ make database
  1. Add a connection URL to example/.env.
  1. Run migrations from the example app.
$ cd example
$ pipenv run python migrate
Developing the docs

Within a pipenv shell, navigate to the docs directory and run the docs development server.

$ make livehtml
You can’t perform that action at this time.