US-Mexico border drug seizures API

The API is built using django-tastypie, and therefore follows Tastypie filtering conventions. The API returns JSON and JSONP responses. This guide is a work in progress — please let us know what's confusing or could work better.

Read more about The Center for Investigative Reporting's findings here.

Seizures

The API includes access to 128,000 individual seizure incidents from January 2005 through early October 2011, as reported by the U.S. Border Patrol and Customs and Border Protection. Seizures by the Border Patrol are separated from those at ports. It's important to note that the agencies' responses to The Center for Investigative Reporting's Freedom of Information Act requests included only areas adjacent to the U.S.-Mexico border. Northern border regions and inland ports are not included in this dataset.

Border Patrol seizures root URI: http://borderseizures.apps.cironline.org/api/v1/bp-seizure/?format=json

CBP port seizures root URI: http://borderseizures.apps.cironline.org/api/v1/port-seizure/?format=json

Filtering

Seizure objects can be filtered by station or drug.

To filter by station:
/api/v1/bp-seizure/?format=json&station__slug=station-sierra-blanca /api/v1/bp-seizure/?format=json&station__slug=station__code=SBT

To filter by drug (Options are "Marijuana", "Cocaine", "Methamphetamine", "Heroin" and "Other"): http://borderseizures.apps.cironline.org/api/v1/bp-seizure/?format=json&drug=Cocaine

A typical Border Patrol seizure object

{
    "date_time": "2005-01-01T00:38:00",
    "event_code": "YUS0501000041",
    "id": 4853,
    "resource_uri": "/api/v1/bp-seizure/4853/",
    "seized_items": [
        {
            "drug": {
                "name": "Marijuana",
                "resource_uri": "/api/v1/bp-stations-drug/1/"
            },
            "weight_kgs": "0.0054431642",
            "weight_lbs": "0.0119749612"
        },
        {
            "drug": {
                "name": "Cocaine",
                "resource_uri": "/api/v1/bp-stations-drug/2/"
            },
            "weight_kgs": "0.0004535970",
            "weight_lbs": "0.0009979134"
        }
    ],
    "station": {
        "code": "YUS",
        "name": "Yuma",
        "resource_uri": "/api/v1/station/101/"
    },
    "suspects": [
        {
            "arrest_method": "Traffic check",
            "count": 1,
            "suspect_status": "USC"
        }
    ]
}
                    
Property name Return type Description
date_time YYYY-MM-DDTHH:MM:SS The date and time of the seizure, in 24-hour format.
event_code String The Border Patrol incident code for this seizure.
resource_uri String The API link to this specific seizure.
seized_items Object A list of seized drugs. Note that there may be more than one drug per seizure incident.
station Object A pointer to the Border Patrol Station where the seizure occurred. This means that the seizure occurred within this station's Area of Responsibility, not necessarily at a given point.
suspects Object A list of the number of suspects detained, if any. Suspects are aggregated by type, i.e. all U.S. citizens (USC) are one object, then another object for suspects with other statuses. The object also includes arrest method codes for the incident.

CBP port seizures object

The only differences between Border Patrol and port of entry seizures is a different format for incident codes, filtering is by port area rather than station, and arrest methods are not included.

Drug totals

Drug totals show aggregate seizure counts and weights by year and month. (A static version of this drives the main chart on the seizure map.) It's important to note that these totals are split between Border Patrol and port seizures.

Border Patrol drug totals root URI: http://borderseizures.apps.cironline.org/api/v1/bp-stations-drug/?format=json

CBP port areas drug totals root URI: http://borderseizures.apps.cironline.org/api/v1/port-areas-drug/?format=json

A typical Drug Totals object

{
    "median_weight": 37.72,
    "name": "Marijuana",
    "resource_uri": "/api/v1/bp-stations-drug/1/",
    "seizure_count": 76459,
    "total_weight": 13234766.57,
    "years": [
        {
            "median_weight": 54.885,
            "monthly_total_seizures": [
                603,
                496,
                482,
                494,
                495,
                489,
                456,
                481,
                546,
                539,
                661,
                754
            ],
            "monthly_total_weights": [
                96883.42,
                112169.04,
                95830.21,
                90307.32,
                151539.5,
                111977.89,
                92534.34,
                78413.51,
                62770.69,
                84402.92,
                138410.57,
                149614.12
            ],
            "seizure_count": 6496,
            "total_weight": 1264853.52,
            "year": 2005
            
        },
        ... (more years, 2005-2011)
    ]
}
                    
Property name Return type Description
median_weight Float The median seizure weight (in pounds) of this drug by the Border Patrol over all years.
name String Name of the drug. Options are Marijuana, Cocaine, Methamphetamine, Heroin and Other.
resource_uri String The API link to this drug.
seizure_count Integer The number of Border Patrol seizure incidents involving this drug over all years.
total_weight Float The total weight (in pounds) of this drug seized by the Border Patrol over all years.
years Array An array of objects for each year of data. Please note that data for 2011 ends in early October. All weights are in pounds.

Border Patrol stations

Border Patrol stations show aggregated statistics for each station. This view may run slowly if trying to load all stations at once.

Border Patrol stations root URI: http://borderseizures.apps.cironline.org/api/v1/station/?format=json

Filtering

Border Patrol Station objects can be filtered by id, code, or slug.

To filter by id:
/api/v1/station/1/?format=json

To filter by code or slug:
/api/v1/station/?format=json&code=SBT /api/v1/station/?format=json&slug=station-sierra-blanca

A typical Border Patrol station object

{
    "address": "10888 Avenue 31E",
    "city": "Wellton",
    "code": "WEL",
    "drug_stats": [
        {
            "median_weight": 0.009,
            "name": "Marijuana",
            "seizure_count": 8938,
            "total_weight": 126124.65,
            "years": [
                {
                    "median_weight": 0.022,
                    "monthly_total_seizures": [
                        18,
                        0,
                        1,
                        1,
                        1,
                        1,
                        3,
                        24,
                        62,
                        2,
                        1,
                        7
                    ],
                    "monthly_total_weights": [
                        206.3,
                        0,
                        3748.93,
                        3885.29,
                        0,
                        1742.86,
                        527.84,
                        44.67,
                        447.97,
                        1187.21,
                        3664.34,
                        1046.27
                    ],
                    "seizure_count": 121,
                    "total_weight": 16501.68,
                    "year": 2005
                },
                ... (more years, 2005-2011)
            ],
        },
        ... (more drugs)
    ],
    "geometry": {
        "coordinates": [
            -114.107909873,
            32.6658859849
        ],
        "type": "Point"
    },
    "id": 99,
    "name": "Wellton",
    "resource_uri": "/api/v1/station/99/",
    "sector": "Yuma",
    "slug": "station-wellton",
    "state": "AZ",
    "total_seizure_count": 9223,
    "type": "Feature",
    "zip": "85356"
}
                    
Property name Return type Description
address String Street address of this Border Patrol station's headquarters.
city String City of this Border Patrol station's headquarters.
code String The Border Patrol's 3-letter code for this station. Can be used to filter individual drug seizures (see above).
drug_stats Array An array of objects for each drug, which in turn each contain objects for each year. The format mimics that of Drug Totals. All weights are in pounds.
geometry GeoJSON Geometry The point location of this station's headquarters.
id Integer Internal database ID of this station.
name String The name of this station.
resource_uri String The API link to this specific station.
sector String The Border Patrol sector this station is part of.
slug String A slugified version of the station name, preceded by "station-".
state String Abbreviated state name of the station's headquarters.
total_seizure_count Integer The total number of seizure incidents in this port area over all years, all drugs combined.
type GeoJSON geometry type Always "Feature"
zip String The station's headquarters' zip code.

CBP port areas

Each CBP port area represents aggregated statistics of several ports of entry that the agency has combined. This view may run slowly if trying to load all port areas at once.

CBP port areas root URI: http://borderseizures.apps.cironline.org/api/v1/port-area/?format=json

Filtering

CBP port area objects can be filtered by id or slug.

To filter by id:
/api/v1/port-area/1/?format=json

To filter by slug:
/api/v1/port-area/?format=json&slug=portarea-san-diego

A typical CBP port area object

{
    "drug_stats": [
        {
            "median_weight": 77.561,
            "name": "Marijuana",
            "seizure_count": 8460,
            "total_weight": 917443.64,
            "years": [
                {
                    "median_weight": 79.264,
                    "monthly_total_seizures": [
                        74,
                        86,
                        125,
                        85,
                        93,
                        97,
                        79,
                        86,
                        85,
                        83,
                        59,
                        58
                    ],
                    "monthly_total_weights": [
                        7214.09,
                        7786.89,
                        18643.36,
                        7039.01,
                        7431.23,
                        8290.37,
                        7429.01,
                        7877.95,
                        8329.87,
                        7158.7,
                        7221.03,
                        4764.63
                    ],
                    "seizure_count": 1010,
                    "total_weight": 99186.14,
                    "year": 2005
                },
                ... (more years, 2005-2011)
            ],
        },
        ... (more drugs)
    ],
    "geometry": {
        "coordinates": [
            -105.64173616240652,
            31.09390442500419
        ],
        "type": "Point"
    },
    "id": 1,
    "name": "El Paso",
    "resource_uri": "/api/v1/port-area/1/",
    "slug": "portarea-el-paso",
    "total_seizure_count": 9046,
    "type": "Feature"
}
                    
Property name Return type Description
drug_stats Array An array of objects for each drug, which in turn each contain objects for each year. The format mimics that of Drug Totals. All weights are in pounds.
geometry GeoJSON Geometry A point location that represents an arbitrary center point of the port area, which is used on the seizure map. It is NOT the location of any port or regional headquarters.
id Integer Internal database ID of this port area.
name String The name of this port area.
resource_uri String The API link to this specific port area.
slug String A slugified version of the port area name, preceded by "portarea-".
total_seizure_count Integer The total number of seizure incidents in this port area over all years, all drugs combined.
type GeoJSON geometry type Always "Feature"