Police API

class police_api.PoliceAPI(**config)[source]
>>> from police_api import PoliceAPI
>>> api = PoliceAPI(user_agent='cops-and-robbers/9.9.9', timeout=60)
Parameters:
  • base_url – The base endpoint URL for the Police API. Default: 'https://data.police.uk/api/'
  • user_agent – The user agent string to use. Default: 'police-api-client-python/<version>'
  • timeout – The timeout in seconds. Default: 30
  • username – The username to authenticate with. Default: None
  • password – The password to authenticate with. Default: None
get_forces()[source]

Get a list of all police forces. Uses the forces API call.

Return type:list
Returns:A list of forces.Force objects (one for each police force represented in the API)
get_force(id, **attrs)[source]

Get an individual forces. Uses the force API call.

Parameters:id – The ID of the force to get information about.
Return type:forces.Force
Returns:The appropriate forces.Force object.
get_neighbourhoods(force)[source]

Get a list of all neighbourhoods for a force. Uses the neighbourhoods API call.

Parameters:force (str or forces.Force) – The force to get neighbourhoods for (either by ID or forces.Force object)
Return type:list
Returns:A list of neighbourhoods.Neighbourhood objects (one for each Neighbourhood Policing Team in the given force).
get_neighbourhood(force, id, **attrs)[source]

Get a specific neighbourhood. Uses the neighbourhood API call.

Parameters:
  • force (str or Force) – The force within which the neighbourhood resides (either by ID or forces.Force object)
  • neighbourhood (str) – The ID of the neighbourhood to fetch.
Return type:

Neighbourhood

Returns:

The Neighbourhood object for the given force/ID.

locate_neighbourhood(lat, lng)[source]

Find a neighbourhood by location. Uses the locate-neighbourhood API call.

Parameters:
  • lat (float or str) – The latitude of the location.
  • lng (float or str) – The longitude of the location.
Return type:

Neighbourhood or None

Returns:

The Neighbourhood object representing the Neighbourhood Policing Team responsible for the given location.

get_dates()[source]

Get a list of available dates. Uses the crimes-street-dates API call.

Return type:list
Returns:A list of str representing each monthly data set, in the format YYYY-MM, most recent first.
get_latest_date()[source]

Get the latest available date. Uses the crimes-street-dates API call (not crime-last-updated, becuase the format differs).

Return type:str
Returns:The most recent data set’s date, in the format YYYY-MM.
get_crime_categories(date=None)[source]

Get a list of crime categories, valid for a particular date. Uses the crime-categories API call.

Return type:list
Parameters:date (str or None) – The date of the crime categories to get.
Returns:A list of crime categories which are valid at the specified date (or at the latest date, if None).
get_crime_category(id, date=None)[source]

Get a particular crime category by ID, valid at a particular date. Uses the crime-categories API call.

Return type:

CrimeCategory

Parameters:
  • id (str) – The ID of the crime category to get.
  • date (str or None) – The date that the given crime category is valid for (the latest date is used if None).
Returns:

A crime category with the given ID which is valid for the specified date (or at the latest date, if None).

get_crime(persistent_id)[source]

Get a particular crime by persistent ID. Uses the outcomes-for-crime API call.

Return type:Crime
Parameters:persistent_id (str) – The persistent ID of the crime to get.
Returns:The Crime with the given persistent ID.
get_crimes_point(lat, lng, date=None, category=None)[source]

Get crimes within a 1-mile radius of a location. Uses the crime-street API call.

Return type:

list

Parameters:
  • lat (float or str) – The latitude of the location.
  • lng (float or str) – The longitude of the location.
  • date (str or None) – The month in which the crimes were reported in the format YYYY-MM (the latest date is used if None).
  • category (str or CrimeCategory) – The category of the crimes to filter by (either by ID or CrimeCategory object)
Returns:

A list of crimes which were reported within 1 mile of the specified location, in the given month (optionally filtered by category).

get_crimes_area(points, date=None, category=None)[source]

Get crimes within a custom area. Uses the crime-street API call.

Return type:

list

Parameters:
  • points (list) – A list of (lat, lng) tuples.
  • date (str or None) – The month in which the crimes were reported in the format YYYY-MM (the latest date is used if None).
  • category (str or CrimeCategory) – The category of the crimes to filter by (either by ID or CrimeCategory object)
Returns:

A list of crimes which were reported within the specified boundary, in the given month (optionally filtered by category).

get_crimes_location(location_id, date=None)[source]

Get crimes at a particular snap-point location. Uses the crimes-at-location API call.

Return type:

list

Parameters:
  • location_id (int) – The ID of the location to get crimes for.
  • date (str or None) – The month in which the crimes were reported in the format YYYY-MM (the latest date is used if None).
Returns:

A list of Crime objects which were snapped to the Location with the specified ID in the given month.

get_crimes_no_location(force, date=None, category=None)[source]

Get crimes with no location for a force. Uses the crimes-no-location API call.

Return type:

list

Parameters:
  • force (str or Force) – The force to get no-location crimes for.
  • date (str or None) – The month in which the crimes were reported in the format YYYY-MM (the latest date is used if None).
  • category (str or CrimeCategory) – The category of the crimes to filter by (either by ID or CrimeCategory object)
Returns:

A list of crime.NoLocationCrime objects which were reported in the given month, by the specified force, but which don’t have a location.