Skip to content

Instantly share code, notes, and snippets.

@ghing

ghing/api_guide.md

Last active December 15, 2015 01:09
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save ghing/5178219 to your computer and use it in GitHub Desktop.
Save ghing/5178219 to your computer and use it in GitHub Desktop.
Download ZIP
API Guide wiki page for SC3 inmate tracker
Raw
api_guide.md

The Cook County Jail Inmate API uses Django Tastypie 0.9.11 to generate an interface to the data scraped from the Cook County Sheriff's Inmate Locator.

The current production version of the API exists at http://cookcountyjail.recoveredfactory.net. The production URL will be used in all API examples.

# Endpoints

The API currently provides information about:

  • Inmates
  • Court dates
  • Court locations

You can access a listing of available endpoints at:

http://cookcountyjail.recoveredfactory.net/api/1.0/?format=json

{

    "countyinmate": {
        "list_endpoint": "/api/1.0/countyinmate/",
        "schema": "/api/1.0/countyinmate/schema/"
    },
    "courtdate": {
        "list_endpoint": "/api/1.0/courtdate/",
        "schema": "/api/1.0/courtdate/schema/"
    },
    "courtlocation": {
        "list_endpoint": "/api/1.0/courtlocation/",
        "schema": "/api/1.0/courtlocation/schema/"
    }

}
# Inmates

Inmate records are the fundamental building blocks of the Cook County Jail Inmate API.

 ## List view

You can access a listing of records at:

http://cookcountyjail.recoveredfactory.net/api/1.0/countyinmate/?format=json

The default number of records is 100.

Let's query a tiny subset of the data by setting the limit parameter and inspecting the output:

http://cookcountyjail.recoveredfactory.net/api/1.0/countyinmate/?format=json&limit=2

{
  "meta": {
    "limit": 2, 
    "next": "/api/1.0/countyinmate/?offset=2&limit=2&format=json", 
    "offset": 0, 
    "previous": null, 
    "total_count": 11
  }, 
  "objects": [
    {
      "age_at_booking": 33, 
      "bail_amount": null, 
      "bail_status": "NO BOND", 
      "booking_date": "2012-12-24T00:00:00", 
      "charges": "POSS AMT CON SUB EXCEPT(A)/(D)", 
      "charges_citation": "720 ILCS 5 12-3(a)(2) [10530]", 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "06-R-1-8-1", 
      "jail_id": "2012-1224081", 
      "race": "BK"
    }, 
    {
      "age_at_booking": 23, 
      "bail_amount": null, 
      "bail_status": "NO BOND", 
      "booking_date": "2012-12-13T00:00:00", 
      "charges": "VIOLATION OF PROBATION", 
      "charges_citation": "000", 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "02-D1-H-3-H", 
      "jail_id": "2012-1213153", 
      "race": "WH"
    }
  ]
}
### Custom parameters #### `related`

Set ?related=1 to include related court dates and locations.

http://cookcountyjail.recoveredfactory.net/api/1.0/countyinmate/?format=json&limit=2&related=1

{
  "meta": {
    "limit": 2, 
    "next": "/api/1.0/countyinmate/?offset=2&limit=2&format=json", 
    "offset": 0, 
    "previous": null, 
    "total_count": 11
  }, 
  "objects": [
    {
      "age_at_booking": 33, 
      "bail_amount": null, 
      "bail_status": "NO BOND", 
      "booking_date": "2012-12-24T00:00:00", 
      "charges": "POSS AMT CON SUB EXCEPT(A)/(D)", 
      "charges_citation": "720 ILCS 5 12-3(a)(2) [10530]", 
      "court_dates": [], 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "06-R-1-8-1", 
      "jail_id": "2012-1224081", 
      "race": "BK"
    }, 
    {
      "age_at_booking": 23, 
      "bail_amount": null, 
      "bail_status": "NO BOND", 
      "booking_date": "2012-12-13T00:00:00", 
      "charges": "VIOLATION OF PROBATION", 
      "charges_citation": "000", 
      "court_dates": [
        {
          "date": "2012-12-31", 
          "id": "7", 
          "location": {
            "id": "9", 
            "location": "Criminal C
        Criminal Courts Building, Room:202
        2650 South California Avenue Room: 202
        Chicago, IL 60608"
          }
        }
      ], 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "02-D1-H-3-H", 
      "jail_id": "2012-1213153", 
      "race": "WH"
    }
  ]
}
#### `format=csv`

Adds CSV-formatted output. If specified, the related parameter will be ignored.

 ### Filtering

Supports standard Tastypie filters, which are based on Django's model filtering language.

See the CountyInmateResource for field and filtering details.

Inmates from 2012 still in jail

Query: discharge_date_earliest__isnull=1&booking_date__gte=2012-01-01&booking_date__lte=2012-12-31

{
  "meta": {
    "limit": 100, 
    "next": "/api/1.0/countyinmate/?booking_date__gte=2012-01-01&offset=100
             &format=json&discharge_date_earliest__isnull=1&limit=100", 
    "offset": 0, 
    "previous": null, 
    "total_count": 9069
  }, 
  "objects": [
    {
      "age_at_booking": 45, 
      "bail_amount": 1000, 
      "bail_status": null, 
      "booking_date": "2013-01-05T00:00:00", 
      "charges": "", 
      "charges_citation": "625 ILCS 5 11-501(a) [12809]", 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "15-HP", 
      "jail_id": "2013-0105197", 
      "race": "BK"
    }, 
    {
      "age_at_booking": 18, 
      "bail_amount": null, 
      "bail_status": "", 
      "booking_date": "2013-01-05T00:00:00", 
      "charges": "", 
      "charges_citation": "", 
      "discharge_date_earliest": null, 
      "gender": "M", 
      "housing_location": "05-", 
      "jail_id": "2013-0105196", 
      "race": "BK"
    },
    // ...
  ]
}

Record view

Append the jail_id field to the inmate URL. e.g.:

http://cookcountyjail.recoveredfactory.net/api/1.0/countyinmate/2012-1231129/?format=json

{
  "age_at_booking": 33, 
  "bail_amount": null, 
  "bail_status": "NO BOND", 
  "booking_date": "2012-12-31T00:00:00", 
  "charges": "RESIDENTIAL BURGLARY", 
  "charges_citation": "720 ILCS 5 19-3(a) [1120000]", 
  "court_dates": [
    {
      "date": "2013-01-10", 
      "id": "23062", 
      "location": {
        "id": "52", 
        "location": "Criminal C
        Criminal Courts Building, Room:704
        2650 South California Avenue Room: 704
        Chicago, IL 60608"
      }
    }
  ], 
  "discharge_date_earliest": null, 
  "gender": "M", 
  "housing_location": "01-F-2-18-2", 
  "jail_id": "2012-1231129", 
  "race": "BK"
}
# Court dates ## List view

You can access a listing of records at:

http://cookcountyjail.recoveredfactory.net/api/1.0/courtdates/?format=json

The default number of records is 2500.

Let's query a tiny subset of the data by setting the limit parameter and inspecting the output:

http://cookcountyjail.recoveredfactory.net/api/1.0/courtdate/?format=json&limit=2

{

    "meta": {
        "limit": 2,
        "next": "/api/1.0/courtdate/?offset=2&limit=2&format=json",
        "offset": 0,
        "previous": null,
        "total_count": 83471
    },
    "objects": [
        {
            "date": "2012-12-13",
            "id": "21",
            "inmate_jail_id": "2012-0815067",
            "location": "Criminal C\nCriminal Courts Building, Room:606\n2650 South California Avenue Room: 606\nChicago, IL 60608\n",
            "location_id": 23
        },
        {
            "date": "2012-12-13",
            "id": "2",
            "inmate_jail_id": "2012-0309243",
            "location": "Criminal C\nCriminal Courts Building, Room:202\n2650 South California Avenue Room: 202\nChicago, IL 60608\n",
            "location_id": 2
        }
    ]

}
### Custom parameters #### `related`

Set ?related=1 to include related court locations and inmate IDs.

http://cookcountyjail.recoveredfactory.net/api/1.0/courtdate/?format=json&limit=1&related=1&offset=400

{

    "meta": {
        "limit": 1,
        "next": "/api/1.0/courtdate/?related=1&limit=1&offset=401&format=json",
        "offset": 400,
        "previous": "/api/1.0/courtdate/?related=1&limit=1&offset=399&format=json",
        "total_count": 83471
    },
    "objects": [
        {
            "date": "2012-12-13",
            "id": "5289",
            "inmate": {
                "age_at_booking": 17,
                "bail_amount": null,
                "bail_status": "NO BOND",
                "booking_date": "2012-06-23T00:00:00",
                "charges": "AGGRAVATED ROBBERY",
                "charges_citation": "720 ILCS 5/18-5",
                "discharge_date_earliest": "2013-03-07T06:43:05.262244",
                "gender": "M",
                "housing_location": "11-BC-1-101",
                "jail_id": "2012-0623220",
                "race": "BK"
            },
            "location": {
                "id": "39",
                "location": "Criminal C\nCriminal Courts Building, Room:207\n2650 South California Avenue Room: 207\nChicago, IL 60608\n"
            }
        }
    ]

}
#### `format=csv`

Adds CSV-formatted output. If specified, the related parameter will be ignored.

 ###Filtering

Supports standard Tastypie filters, which are based on Django's model filtering language.

# Court locations

Court locations are collected every time an inmate gets a new court date. We should be able to tie them to specific types of court (e.g. bond court, sentencing court) and possibly even judges based on public schedules.

 ## List view

You can access a listing of records at:

http://cookcountyjail.recoveredfactory.net/api/1.0/courtlocation/?format=json

The default number of records is 2500.

Let's query a tiny subset of the data by setting the limit parameter and inspecting the output:

http://cookcountyjail.recoveredfactory.net/api/1.0/courtlocation/?format=json&limit=2

{
  "meta": {
    "limit": 2, 
    "next": "/api/1.0/courtlocation/?format=json&limit=2&offset=2", 
    "offset": 0, 
    "previous": null, 
    "total_count": 1255
  }, 
  "objects": [
    {
      "id": "1", 
      "location": "Criminal C
        Criminal Courts Building, Room:506
        2650 South California Avenue Room: 506
        Chicago, IL 60608"
    }, 
    {
      "id": "2", 
      "location": "Criminal C
        Criminal Courts Building, Room:202
        2650 South California Avenue Room: 202
        Chicago, IL 60608"
    }
  ]
}
### Custom parameters #### `related`

Set ?related=1 to include related court dates and inmate IDs.

http://cookcountyjail.recoveredfactory.net/api/1.0/courtlocation/?format=json&limit=1&related=1&offset=400

{
  "meta": {
    "limit": 1, 
    "next": "/api/1.0/courtlocation/?offset=401&limit=1&format=json&related=1", 
    "offset": 400, 
    "previous": "/api/1.0/courtlocation/?offset=399&limit=1&format=json&related=1", 
    "total_count": 1255
  }, 
  "objects": [
    {
      "court_dates": [
        {
          "date": "2012-12-14", 
          "id": "2781", 
          "inmate": "2012-1208068"
        }
      ], 
      "id": "400", 
      "location": "Branch 34
        Branch 98, Room:101
        2650 South California Avenue Room: 101
        Chicago, IL 60608"
    }
  ]
}
#### `format=csv`

Adds CSV-formatted output. If specified, the related parameter will be ignored.

 ### Record view

Append the id field to the inmate URL. e.g.:

http://cookcountyjail.recoveredfactory.net/api/1.0/courtlocation/200/?format=json

{
  "court_dates": [
    {
      "date": "2013-01-10", 
      "id": "749", 
      "inmate": "2011-0901023"
    }, 
    {
      "date": "2013-01-30", 
      "id": "5927", 
      "inmate": "2012-0124199"
    }
  ], 
  "id": "200", 
  "location": "Skokie
        Rolling Meadows, Room:109
        2121 West Euclid Avenue Room: 109
        Rolling Meadows, IL 60008"
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment