Keep in mind, I'm still not sure whether this API is truly public or not. I'm just going to document it, so please use at your own risk. These docs are merely an experiment in documenting an API from afar, so it's kind of a fun reverse engineering project.

I can only hope you use it for good, and not to profit further from prisoners or the prison system, but it's not up to me to tell you how to use this - or whether you should at all!

This API is used by their website bop.gov. Thus much of the location object properties and such are geared towards use by a website. I've discovered endpoints and parameters by digging around in the javascripts on bop.gov. I suggest looking for more!

I don't pretend to own or have the rights to any data from this api or the api itself.

USE THIS API AT YOUR OWN RISK

Returns data about specific bop facilities, using the facility code

Endpoint:

 http://www.bop.gov/PublicInfo/execute/phyloc 

Params:

Param Description
todo use query. again, not sure what this does
output the type of output. json, xml
code The three character prison code. Required!

Example:

 http://www.bop.gov/PublicInfo/execute/phyloc?todo=query&output=json&code=HER 

Response Object:


{
    "Visiting": [
        {
            "code": "her",
            "name": "HERLONG FCI",
            "visitingNotes": "These are typical visiting hours and may not cover all cases.  Please become familiar with the visiting policy which can be downloaded from the www.bop.gov website.",
            "street": "741-925 ACCESS ROAD A-25",
            "city": "HERLONG",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "530",
            "number": "827-8000",
            "visitDays": [
                {
                    "code": "her",
                    "notes": " ",
                    "camp": true,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Sunday",
                    "day": 0,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                },
                {
                    "code": "her",
                    "notes": " ",
                    "camp": false,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Sunday",
                    "day": 0,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                },
                {
                    "code": "her",
                    "notes": " ",
                    "camp": true,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Saturday",
                    "day": 6,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                },
                {
                    "code": "her",
                    "notes": " ",
                    "camp": false,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Saturday",
                    "day": 6,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                },
                {
                    "code": "her",
                    "notes": " ",
                    "camp": true,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Federal Holiday",
                    "day": 7,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                },
                {
                    "code": "her",
                    "notes": " ",
                    "camp": false,
                    "fsl": false,
                    "fdc": false,
                    "dayString": "Federal Holiday",
                    "day": 7,
                    "startTime": "8:00 AM",
                    "endTime": "3:00 PM"
                }
            ]
        }
    ],
    "Messages": {},
    "Addresses": [
        {
            "name": "HERLONG FCI",
            "code": "HER",
            "addressType": "3",
            "addressTypeName": "Inmate Mail/Parcels",
            "region": "WXR",
            "street": "P.O. BOX 800",
            "street2": "",
            "city": "HERLONG",
            "county": "LASSEN",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "",
            "number": "",
            "faxAreaCode": "",
            "faxNumber": "",
            "faclTypeDescription": "Federal Correctional Institution"
        },
        {
            "name": "HERLONG FCI",
            "code": "HER",
            "addressType": "6",
            "addressTypeName": "Inmate Mail/Parcels - Camp",
            "region": "WXR",
            "street": "P.O. BOX 800",
            "street2": "",
            "city": "HERLONG",
            "county": "LASSEN",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "",
            "number": "",
            "faxAreaCode": "",
            "faxNumber": "",
            "faclTypeDescription": "Federal Correctional Institution"
        },
        {
            "name": "HERLONG FCI",
            "code": "HER",
            "addressType": "1",
            "addressTypeName": "Physical Address",
            "region": "WXR",
            "street": "741-925 ACCESS ROAD A-25",
            "street2": "",
            "city": "HERLONG",
            "county": "LASSEN",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "530",
            "number": "827-8000",
            "faxAreaCode": "530",
            "faxNumber": "827-8024",
            "faclTypeDescription": "Federal Correctional Institution"
        },
        {
            "name": "HERLONG FCI",
            "code": "HER",
            "addressType": "5",
            "addressTypeName": "Shipping",
            "region": "WXR",
            "street": "741-925 ACCESS ROAD A-25",
            "street2": "",
            "city": "HERLONG",
            "county": "LASSEN",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "",
            "number": "",
            "faxAreaCode": "",
            "faxNumber": "",
            "faclTypeDescription": "Federal Correctional Institution"
        },
        {
            "name": "HERLONG FCI",
            "code": "HER",
            "addressType": "2",
            "addressTypeName": "Staff Mail",
            "region": "WXR",
            "street": "P.O. BOX 900",
            "street2": "",
            "city": "HERLONG",
            "county": "LASSEN",
            "state": "CA",
            "zipCode": "96113",
            "areaCode": "",
            "number": "",
            "faxAreaCode": "",
            "faxNumber": "",
            "faclTypeDescription": "Federal Correctional Institution"
        }
    ],
    "Locations": [
        {
            "code": "HER",
            "name": "Herlong",
            "nameTitle": "FCI Herlong",
            "nameDisplay": "Herlong FCI",
            "complexCode": "",
            "type": "FCI",
            "securityLevel": "Medium",
            "region": "Western Region",
            "latitude": "40.14406729825646",
            "longitude": "-120.16358613967896",
            "url": "/locations/institutions/her/",
            "timeZone": "P",
            "address": "741-925 ACCESS ROAD A-25",
            "city": "HERLONG",
            "state": "CA",
            "zipCode": "96113",
            "phoneNumber": "530-827-8000",
            "contactEmail": "HER/ExecAssistant@bop.gov",
            "locationtype": "inst",
            "privateFacl": "f",
            "gender": "male",
            "special": false,
            "faclTypeDescription": "Federal Correctional Institution",
            "hasCamp": true,
            "imageNormal": "/locations/institutions/her/HER_lrg.jpg",
            "imageSmall": "/locations/institutions/her/HER_sm.jpg",
            "hasFsl": false,
            "hasFdc": false
        }
    ],
    "Popreport": {
        "TOTALPOPULATION": 1617,
        "CCMTOTAL_FORMATTED": "0",
        "TOTALPOPULATION_FORMATTED": "1,617",
        "CCM": [],
        "CCMTOTAL": 0,
        "PRIVATETOTAL_FORMATTED": "0",
        "Notice": "Output based on search request",
        "PRIVATE": [],
        "BOPTOTAL": 1617,
        "BOP": [
            {
                "code": "HER",
                "Name": "HERLONG FCI",
                "state": "CA",
                "popCount": 1491,
                "groupDescription": "HERLONG FCI",
                "sortKey": "0001",
                "sortNameKey": "HERLONG FCI0000",
                "sortpzapSequence": "0000",
                "indentationIndicator": "N",
                "recordtype": "T"
            },
            {
                "code": "HER",
                "Name": "HERLONG-CAMP",
                "state": "CA",
                "popCount": 126,
                "groupDescription": "HERLONG FCI",
                "sortKey": "0001",
                "sortNameKey": "HERLONG FCI0001",
                "sortpzapSequence": "0001",
                "indentationIndicator": "Y",
                "recordtype": "T"
            }
        ],
        "BOPTOTAL_FORMATTED": "1,617",
        "DATEMODIFIED": "March 20, 2014",
        "PRIVATETOTAL": 0
    },
    "Lockdown": [],
    "FormToken": "pub32364info"
}

Returns an Index of BOP Facilities

Endpoint:

 http://www.bop.gov/PublicInfo/execute/locations/?todo=query&output=json 

Returns a blank Message and Locations object which contains an array of Location objects - a very shortened version of the Locations object above.

I haven't found any parameters used to sort, filter, limit the index yet.

Object Properties

Property Example Values Description
code ACC The Unique ID for this facility - in this case all caps (note that when you return all data, it's in all caps)
url /locations/ci/acc Relative path from www.bop.gov
type CI Bop codes for facility types. There should be an index of these somewhere... see: facylTypeDescriptoion
faclTypeDescription Correctional Institution The human-readable facility type name
locationtype
privateFacl t/f Apparently a faux boolean for whether or not this facility is private

Notes:

  • Not all properties are proper camel case
  • Some properties will vanish from the object rather than returning NULL
  • Location objects from the index return a primary address. This address is NOT the same as for sending inmates mail or parcels, nor is it the address for prison camps, either. More specific addresses can be fetched from phyLoc.

Example:

 http://www.bop.gov/PublicInfo/execute/locations/?todo=query&output=json 

Returns:


{
    "Messages": {},
    "Locations": [
        {
            "code": "ACC",
            "name": "Adams County",
            "nameTitle": "CI Adams County",
            "nameDisplay": "Adams County CI",
            "complexCode": "",
            "type": "CI",
            "securityLevel": "Low",
            "region": "Southeast Region",
            "latitude": "31.555353139426984",
            "longitude": "-91.21853828430176",
            "url": "/locations/ci/acc/",
            "timeZone": "C",
            "address": "20 HOBO FORK ROAD",
            "city": "NATCHEZ",
            "state": "MS",
            "zipCode": "39120",
            "phoneNumber": "601-304-2500",
            "contactEmail": "ACC/General@bop.gov",
            "locationtype": "inst",
            "privateFacl": "t",
            "gender": "male",
            "special": false,
            "faclTypeDescription": "Correctional Institution",
            "hasCamp": false,
            "imageNormal": "",
            "imageSmall": "",
            "hasFsl": false,
            "hasFdc": false
        },
        {
            "code": "ALD",
            "name": "Alderson",
            "nameTitle": "FPC Alderson",
            "nameDisplay": "Alderson FPC",
            "complexCode": "",
            "type": "FPC",
            "securityLevel": "Minimum",
            "region": "Mid-Atlantic Region",
            "latitude": "37.725277605059226",
            "longitude": "-80.65844535827637",
            "url": "/locations/institutions/ald/",
            "timeZone": "E",
            "address": "GLEN RAY RD. BOX A",
            "city": "ALDERSON",
            "state": "WV",
            "zipCode": "24910",
            "phoneNumber": "304-445-3300",
            "contactEmail": "ALD/ExecAssistant@bop.gov",
            "locationtype": "inst",
            "privateFacl": "f",
            "gender": "female",
            "special": false,
            "faclTypeDescription": "Federal Prison Camp",
            "hasCamp": false,
            "imageNormal": "/locations/institutions/ald/ALD_lrg.jpg",
            "imageSmall": "/locations/institutions/ald/ALD_sm.jpg",
            "hasFsl": false,
            "hasFdc": false
        },
        [...]
}

Endpoint:

 http://www.bop.gov/PublicInfo/execute/inmateloc

Got this one working! finally! It was remarkably easy, just had to serialize form values to see what was happening.

Param Example Description
inmateNumType IRN The number type. Required for num search.
inmateNum 57978-060 The inmate number. Required for num search.

Example:

 http://www.bop.gov/PublicInfo/execute/inmateloc?todo=query&output=json&inmateNumType=IRN&inmateNum=57978-060 

Returns:

{
    "InmateLocator": [
        {
            "nameLast": "STEVENS",
            "nameFirst": "CONNOR",
            "nameMiddle": "C",
            "sex": "Male",
            "race": "White",
            "age": "22",
            "inmateNum": "57978-060",
            "inmateNumType": "",
            "releaseCode": "",
            "faclCode": "MCK",
            "faclName": "McKean",
            "faclType": "FCI",
            "faclURL": "/locations/institutions/mck/",
            "projRelDate": "05/15/2019",
            "actRelDate": "",
            "suffix": ""
        }
    ],
    "Captcha": false,
    "Messages": {},
    "FormToken": "pub29342info"
}

PDF Resource URLS

Though every facility does not necessarily have these documents, they can be accessed from here:

Security

  • www.bop.gov does not support ssl - for the website or the API. Boo
  • no authentication is necessary