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:

Visiting Hours http://www.bop.gov/locations/institutions/[code]/[CODE]_visit_hours.pdf
Legal Visting Guide http://www.bop.gov/locations/institutions/[code]/[CODE]_legal_visiting_guide.pdf
Admissions & Orientation Handbook http://www.bop.gov/locations/institutions/[code]/[CODE]_aohandbook.pdf
Commissary List http://www.bop.gov/locations/institutions/[code]/[CODE]_CommList.pdf

Security

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

BOP API Docs

Introduction

Disclaimer

USE THIS API AT YOUR OWN RISK

Location

Endpoint:

Params:

Example:

Response Object:

Locations

Endpoint:

Object Properties

Notes:

Example:

Returns:

Inmate Locator

Endpoint:

Example:

Other Notes

PDF Resource URLS

Security