The Code for America API. Tracks and motivates activity and participation across the civic technology movement.
Python HTML Other
Pull request Compare This branch is 1023 commits ahead, 3 commits behind chihacknight:master.
tdooner Merge pull request #336 from codeforamerica/bug/update-keeps-crashing
Prioritize syncing official CfA brigades
Latest commit 7ec17c2 Aug 7, 2018
Permalink
Failed to load latest commit information.
migrations Add `logo_url` to Organization API response Jan 26, 2018
scripts pep8 remaining issues and make flake8 test required Nov 4, 2015
static Tweaked CSS Apr 1, 2014
templates Update "upcoming_events" to return events that haven't ended yet Feb 6, 2018
test Tolerate new keys in issues' `label` dicts Aug 4, 2018
.gitignore Gitignore hidden mac files Jan 21, 2016
.travis.yml Move flake8 config into setup.cfg Jan 10, 2018
LICENSE Initial commit Sep 18, 2013
Procfile tinkering with gunicorn settings Nov 23, 2015
README.md Update README.md Feb 5, 2016
app.py Update "upcoming_events" to return events that haven't ended yet Feb 6, 2018
blog.xml Clean up sample blog posts Dec 29, 2014
blog_another.xml more dummy data for testing Jan 14, 2015
blog_fewer.xml added support for new test, affirming that objects that disappear bet… Jan 16, 2015
feeds.py fixed some small code formatting issues Nov 3, 2015
meetup_events.json Save organizations' meetup events Mar 12, 2014
meetup_events_another.json improved test to check all children of deleted project Jan 14, 2015
meetup_events_fewer.json added support for new test, affirming that objects that disappear bet… Jan 16, 2015
models.py Tolerate new keys in issues' `label` dicts Aug 4, 2018
newrelic-staging.ini Staging new relic Dec 10, 2014
newrelic.ini Revert "STAGING config for newrelic." Mar 9, 2015
org_sources.csv add preferred option for getting orgs from json Dec 22, 2015
requirements.txt Remove cffi dependency Aug 6, 2018
run_update.py Prioritize syncing official CfA brigades Aug 7, 2018
runtime.txt Upgrade Python 2.7.6 -> 2.7.15 on Heroku Aug 6, 2018
setup.cfg Move flake8 config into setup.cfg Jan 10, 2018
test_org_sources.csv updated tests for JSON org source Dec 22, 2015
utils.py pep8 remaining issues and make flake8 test required Nov 4, 2015

README.md

Stories in Ready Build Status

The Code for America API

What the CFAPI is

Code for America has developed this API to track all the activity across the civic technology movement. Our goal is to measure and motivate the movement by recognizing participation. The CFAPI describes an organization's projects, stories, and events.

The tools that the Brigades and other groups use to do their fine deeds are all different. The CFAPI does the difficult job of being able to track these activities no matter what tools an organization is using. The participants don't need to change their activities to be included.

How it works

To get the information for the CfAPI, Code for America maintains a list of civic tech organizations and once an hour checks their activity on Meetup.com, their blog, and their GitHub projects. Other services and support for noncode projects are slowly being added. More technical details below.

Projects powered by the CFAPI

Example Response

See the full documentation at http://codeforamerica.org/api

Response for http://codeforamerica.org/api/organizations/Code-for-San-Francisco

{
  "all_events": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/events",
  "all_issues": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/issues",
  "all_projects": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/projects",
  "all_stories": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/stories",
  "api_url": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco",
  "city": "San Francisco, CA",
  "current_events": [
    {
      "api_url": "http://codeforamerica.org/api/events/710",
      "created_at": "2014-02-26 21:05:21",
      "description": null,
      "end_time": null,
      "event_url": "http://www.meetup.com/Code-for-San-Francisco-Civic-Hack-Night/events/193535742/",
      "id": 710,
      "location": null,
      "name": "Weekly Civic Hack Night",
      "organization_name": "Code for San Francisco",
      "start_time": "2014-08-27 18:30:00 -0700"
    },
    ...
  ],
  "current_projects": [
    {
      api_url: "http://codeforamerica.org/api/projects/122",
      categories: null,
      code_url: "https://github.com/sfbrigade/localfreeweb.org",
      description: "Front end for the Local Free Web project",
      github_details: { ... },
      id: 122,
      issues: [ ... ],
      last_updated: "Thu, 24 Jul 2014 22:01:17 GMT",
      link_url: null,
      name: "localfreeweb.org",
      organization: {},
      organization_name: "Code for San Francisco",
      tags: ["digital access","bus stops"],
      type: null,
      status: "Official"
      commit_status: "success"
    },
    ...
  ],
  "current_stories": [
    {
      "api_url": "http://codeforamerica.org/api/stories/10",
      "id": 10,
      "link": "https://groups.google.com/d/msg/code-for-san-francisco/9OewkHV-D1M/0UW_ye9UXc8J",
      "organization_name": "Code for San Francisco",
      "title": "Hack Night Project Pick List",
      "type": "blog"
    },
    ...
  ],
  "id" : "Code-for-San-Francisco",
  "events_url": "http://www.meetup.com/Code-for-San-Francisco-Civic-Hack-Night/",
  "last_updated": 1409087294,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "name": "Code for San Francisco",
  "past_events": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/past_events",
  "projects_list_url": "https://docs.google.com/spreadsheet/pub?key=0ArHmv-6U1drqdDVGZzdiMVlkMnRJLXp2cm1ZTUhMOFE&output=csv",
  "rss": "",
  "started_on": "2014-07-30",
  "type": "Brigade",
  "upcoming_events": "http://codeforamerica.org/api/organizations/Code-for-San-Francisco/upcoming_events",
  "website": "http://codeforsanfrancisco.org/"
}

History

The need for a way to show off good civic tech projects was apparent. Several Brigades had all started working on ways to track their projects. They were working separately on the same idea at the same time. The CFAPI is a generalization of the great work done by:

Open City Open City

Beta NYC Beta NYC

Code for Boston Code for Boston

*For the full story behind this API, read this.

This repository is forked from Open City's Civic Json Worker

Future

We hope that this experiment of tracking activity within a community is useful for other groups besides the civic technology movement. We will begin working with other groups to see if an instance of the CfAPI is useful for them.

We also want to add support for many more services to be included, such as events from Eventbrite. Our goal is for any organization to use any tool to do their work and we will integrate with them.

How to add your Brigade to the API

Submit a Pull Request with your brigade's information to the Brigade Information repository. Instructions are included in that repo's README.

Civic.json

To add extra data about your projects to the CfAPI, include a civic.json file in the top level of your repo.

Currently we accept status and tags as fields in the civic.json.

An example civic.json file

{
    "status": "Production",
    "tags": ["slack", "bot", "integration", "python", "flask", "glossary", "dictionary"]
}

This project could then be easily found by searching the CfAPI like http://codeforamerica.org/api/projects?q=production,slack,bot

The civic.json idea comes from BetaNYC and still has an active discussion about its spec.

Civic Tech Issue Finder

Once you've got your organization's GitHub projects on the API, all of your groups open GitHub Issues will be seen in the Civic Tech Issue Finder. Use the label "help wanted" to get the most exposure. More info on that project's README.

Installation

The CFAPI is built on Flask and Python. The app.py file describes the models and routes. The run_update.py file runs once an hour and collects all the data about the different Brigades. Both tests.py and run_update_test.py are automatically run by Travis-CI whenever a new commit is made. The production service lives on Heroku. Please contact us with any questions.

Development setup

Requirements

  • PostgreSQL Database - How To

Environmental variables

Set these up in a local .env file.

Project setup

$ pip install -r requirements.txt
  • Set up a new database
createdb cfapi
python app.py createdb
  • Run the updater

The run_update.py script will be run on Heroku once an hour and populate the database. To run locally, try:

python run_update.py

You can update just one organization if you need by using:

python run_update.py --name "Beta NYC"

For quicker update testing, use a shorter list of orgs by calling run_update.py with the --test flag:

python run_update.py --test
  • Start the API
env `cat .env` python app.py runserver
  • or use foreman to mimic how the CfAPI runs on Heroku.
foreman start
  • Visit localhost:5000 in your browser to see the results
http://localhost:5000/api/organizations/Code-for-America

Deployment

Deployment is typically on Heroku. Follow this tutorial for basic information on how to setup the project.

Environmental variables

These must be set:

  • GITHUB_TOKEN
  • MEETUP_KEY (if used)

DATABASE_URL will be handled by Heroku.

Project setup

  • Initialize the database
heroku run bash
python -c 'from app import db; db.create_all()'

Tests

  • Set up a new database
createdb civic_json_worker_test
python -c 'from app import db; db.create_all()'

createdb peopledbtest
psql peopledbtest < test/peopledbtest.pgsql

green -vvv --run-coverage to run everything at once.

green test/updater -vvv to test the run_update process.

green test/updater -vvv --run-coverage to test the run_update process with coverage.

green test/integration -vvv to test the API.

green test/integration -vvv --run-coverage to test the API with code coverage.

Codestyle (PEP8 and co.)

The project ships with flake8 to track style, perform a flake8 check by calling

flake8 . --exclude=migrations,test --ignore=E501,E711,E712

Migrations

Migrations are handled through flask-migrate

Contacts

Contributing

Here are some ways you can contribute:

  • by reporting bugs
  • by suggesting new features
  • by translating to a new language
  • by writing or editing documentation
  • by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
  • by refactoring code
  • by closing issues
  • by reviewing patches
  • financially

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. You can indicate support for an existing issue by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug.

Submitting a Pull Request

  1. Fork the project.
  2. Create a topic branch.
  3. Implement your feature or bug fix.
  4. Write tests!
  5. Run a migration if needed.
  6. Commit and push your changes.
  7. Submit a pull request.

Copyright

Copyright (c) 2015 Code for America.