GitSpatial – A Spatial API for your GitHub-hosted GeoJSON

GitHub supports rendering GeoJSON files directly in their website. And with help from geojson.io you can easily create, update and edit your GeoJSON features right in the browser.

I thought it would be fun to create a spatial API that fronts and syncs your GeoJSON hosted by GitHub. So, I built GitSpatial.

How it Works

When you first visit the site, you can log in with your GitHub account. You’ll be asked to allow GitSpatial access to your public repos (maybe private ones later?). When you grant access, we’ll get a list of your repos. Since you might have many repos, and many of those won’t have any GeoJSON, you are responsible for syncing any repos that do. Syncing is a one-time process that lets our service know that we should keep track of changes in this repo. When you sync we add a post-receieve hook to your repo settings so GitSpatial is notified when changes are made.

Once your repo is synced, the final step is to sync individual feature sets (files) that you want GitSpatial to keep track of. Again, you could have many GeoJSON files in a repo that you just don’t care about syncing, so we don’t want to bother tracking updates to those. As with repo syncing, this is a one-time process, so you won’t have to worry about it again.

When your feature set is done syncing, you’ll have immediate API access to it.

Using the API

Each feature set is shared as a separate resource like:

http://gitspatial.com/api/v1/JasonSanford/mecklenburg-gis-opendata/parks

or:

http://gitspatial.com/api/v1/JasonSanford/cambridgegis_data/utility_poles

GETing these resources will simply return a paginated set of data.

You can also search for features near a certain point. Suppose you wanted to find parks near a certain area. Simply specify a lat, lon and distance to search:

http://gitspatial.com/api/v1/JasonSanford/mecklenburg-gis-opendata/parks?lat=35.256&lon=-80.809&distance=2000

What if you’re creating a web mapping application and you want to show all utility poles in the map window. Just add a bbox URL parameter:

http://gitspatial.com/api/v1/JasonSanford/cambridgegis_data/utility_poles?&bbox=-71.1168622970581,42.36897629762196,-71.11066102981567,42.37254320340071

I’ve also added GitSpatial support in Leaflet Vector Layers. There are a couple of demos to check out out too. Below, you can see how updates to the data, in this case with geojson.io are almost immediately available in Leaflet Vector Layers.

What’s Next

  • Private Repos – For now every repo/feature set you sync is publicly available. I’d really like to add support for OAuth API access for private repos.
  • Attribute Searching – For GeoJSON feature properties I’m just dumbly storing the JSON as a string in a properties field. Ideally I’d like to use something like HStore to allow indexing and searching of this data.
  • Support non-*.geojson Files – Maybe you store your files as *.json or even *.topojson. We currently don’t look at these, but maybe soon.

You can view the site live at http://gitspatial.com. The source code is also available. As always, feature requests and bug fixes are welcome.