Skip to content

API guide

Jump to bottom Edit New page
Brian Everett Peterson edited this page Mar 2, 2014 · 17 revisions

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
  • Housing locations
  • Housing histories
  • Charges histories
  • Daily population summaries

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/courtdate/?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.

TODO: Add filtering examples once pull request #55 is merged

Record view

Append the id field to the court date list URL. e.g.:

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

{

    "date": "2012-12-14",
    "id": "200",
    "inmate_jail_id": "2012-1208089",
    "location": "Branch 44\nBranch 44, Room:2\n3150 West Flournoy Room: 2\nChicago, IL 60612\n",
    "location_id": 57

}
# 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"
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally