Open-source fork of code behind
Python JavaScript Other
Switch branches/tags
Nothing to show
Pull request Compare This branch is 3 commits ahead, 2154 commits behind openplans:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


OpenBlock is a web application that allows users to browse and search their local area for "hyper-local news" - to see what's going on recently in the immediate geographic area.

OpenBlock began life as the open-source code released by in June 2009. Originally created by Adrian Holovaty and the Everyblock team, it is now developed as an open-source (GPL) project at

Funding for the initial creation of Everyblock and the ongoing development of OpenBlock is provided by the Knight Foundation.

System Requirements

  • Linux, OSX, or some other Unix flavor.

  • python 2.6 (2.7 might work)

  • python-dev (python development libraries, whatever that's called on your system)

  • postgresql

  • postgis

  • libgdal

  • libxml2

  • libxslt

  • git

For system-specific lists of packages to install, see Openblock Installation Requirements and let us know if your system isn't listed there!

Quickstart: Install and Set Up Demo Site

These instructions will install the software in an isolated python environment using virtualenv For detailed instructions and further steps, see obdemo/README.txt::

$ git clone git:// openblock
$ cd openblock
$ python

Optionally you can edit obdemo/obdemo/ at this stage. It's a good idea to look at it, at least to get an idea of what can be configured.

Now you can set up the database and start the server::

$ source bin/activate
$ sudo -u postgres oblock setup_dbs
$ oblock sync_all
$ ./ runserver

If all goes well, you should be able to visit the demo site at: http://localhost:8000.

If you encounter problems, double check that you have the basic system requirements installed and then have a look at the step-by-step instructions in obdemo/README.txt.

For more help, you can try the ebcode group or look for us in the #openblock IRC channel on

For Developers

This is a Django application, so it's highly recommended that you have familiarity with the Django Web framework. The best places to learn are the official documentation and the free Django Book. Note that OpenBlock requires Django 1.1 and as of this writing does not yet work with Django 1.2 or later.

Before you dive in, it's highly recommend you spend a little bit of time browsing around and/or to get a feel for what this software does.

Also, for a light conceptual background on some of this, particularly the data storage aspect, watch the video "Behind the scenes of"

Creating a Custom Site Based on OpenBlock

This is documented in the "Quickstart" section of ebpub/README.TXT. For an example, have a look in obdemo/ which was set up in that fashion.

For installation in this case, you can just use the script and do the rest of the setup by hand. You can look at to get an idea of what needs doing, and/or modify it for your own use.

Things You Will Need

Details are in ebpub/README.TXT, but briefly to get anything useful out of your site, at mininum you will need to do the following:

  1. A database of streets in your city; for example TIGER/Line files See ebpub/README.TXT

  2. Decide what locations are interesting in your area - for example, neighborhoods, zip codes. Obtain shapefiles of the boundaries of those locations, and feed them in. See ebpub/README.TXT

  3. Decide what news sources you want to feed in.

    a. Configure the system with schemas for them. See ebpub/README.TXT

    b. Write scraper scripts to retrieve your news sources and feed it in. See ebdata/README.TXT and ScraperScripts wiki

Yes, this is a lot of work. For more documentation (in progress), see also the wiki articles of Data, and Ideal Feed Format.

The obdemo/bin/ script does all this for the demo site. You can dive into the other scripts that it calls to get more details on how it all works.

Main Code Packages

This distribution contains a number of packages, summarized below:


The code and configuration used by OpenBlock. This is useful as an example of how to set up your own site based on OpenBlock, and is a great place to start. It primarily uses the ebpub package, and is set up with Boston, MA as the area of interest.

For more information, see obdemo/README.txt


Publishing system for block-specific news, as used by

This is the core of an OpenBlock site, providing the web interface that users see as well as the underlying data models. You need this.

For more information, see ebpub/README.TXT


Code to help write scripts that import/crawl/parse data into ebpub.

You will need to write such scripts to get OpenBlock to do anything useful; that is how you feed local news into the system.

For more information, see ebdata/README.TXT


Administrative UI, installation and utilities package for OpenBlock

Other Packages


The blog application used by Everyblock blog

Only of interest if you want to bundle a simple blog with your OpenBlock site; you can probably ignore this.

For more information, see ebblog/README.TXT


The eb map system. This is mostly used for rendering and serving map tiles with Mapnik. This package is optional and not installed by default.

For more information, see ebgeo/README.TXT


Internal applications for the EveryBlock team.

Most OpenBlock users probably won't need this. Not used by obdemo.

ebinternal consists of two apps, citypoll and feedback. citypoll powers EveryBlock's city voting system, both on and on the iPhone app. feeback manages the feedback received from the feedback forms at the bottom of almost every page on

For more information, see ebinternal/README.TXT


A basic wiki.

I'm not even sure if this is used on anymore. Probably not useful to most OpenBlock users.

For more information, see ebwiki/README.TXT


This package contains code/templates that are specific to They were released to fulfill the terms of the grant that funded EveryBlock's development and are likely not of general use, with the possible exception of scraper scripts in everyblock/cities/ and everyblock/states/ which may at least be useful as examples of how to write scrapers.

For more information, see everyblock/README.TXT