ukpolice Package

ukpolice Package

An API for the UK Police Data Service

As part of the data.gov.uk program the UK Government has released information for UK Police forces across the country via an API. The API provides a rich data source for information, including

  • Neighbourhood team members
  • Upcoming events
  • Crime statistics at both street and neighbourhood level
  • Outcomes for street level crimes
  • Nearest police stations

The API is implemented as a standard JSON web service using HTTP GET requests. Full request and response examples are provided in the documentation.

This module provides a method to interface with this API without having to worry about making appropriate REST calls, or formatting the request data

to the required structure.

crime Module

class ukpolice.crime.Crime(json_object)[source]

An instance of a crime, as provided by the API

Note

This class should never be initiated directly. It should be returned from Police.Force

__init__(json_object)[source]

Create Crime Object.

This should not be called directly, only from one of the module methods

btp_location[source]

For BTP locations, the type of location at which this crime was recorded. If the Crime.location_type is not BTP return None

category[source]

Category of the crime. Returns a crime category as ...

context[source]

Extra information about the crime (if applicable)

crime_id[source]

64-character unique identifier for that crime.

date[source]

Year and month of the crime

location_type[source]

The type of the location. Either Force or BTP: Force indicates a normal police force location; BTP indicates a British Transport Police location. BTP locations fall within normal police force boundaries.

outcome[source]

Return list of outcomes

The full category name is returned IMPORTANT NOTE: This element may not be present for all crimes

Code Name awaiting-court-result Awaiting court outcome unable-to-proceed Court case unable to proceed local-resolution Local resolution no-further-action No further action at this time deprived-of-property Offender deprived of property fined Offender fined absolute-discharge Offender given absolute discharge cautioned Offender given a caution penalty-notice-issued Offender given a penalty notice community-penalty Offender given community sentence conditional-discharge Offender given conditional discharge suspended-sentence Offender given suspended prison sentence imprisoned Offender sent to prison other-court-disposal Offender otherwise dealt with compensation Offender ordered to pay compensation sentenced-in-another-case Suspect charged as part of another case charged Suspect charged not-guilty Defendant found not guilty sent-to-crown-court Defendant sent to Crown Court unable-to-prosecute Unable to prosecute suspect under-investigation Under investigation

point[source]

Approximate location of the crime

street[source]

The approximate street where the crime occurred

ukpolice.crime.at_location_by_id(location_id, results_month=None)[source]

Returns just the crimes which occurred at the specified location

http://data.police.uk/docs/method/crimes-at-location/

Note: Returns just the crimes which occurred at the specified location, rather than those within a radius. If given latitude and longitude, finds the nearest pre-defined location and returns the crimes which occurred there.

Arguments:
location_id: Valid IDs are returned by other methods which return location information. results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.at_location_by_point(point, results_month=None)[source]

Returns just the crimes which occurred at the nearest pre-defined location to the supplied Point

http://data.police.uk/docs/method/crimes-at-location/

Arguments:
location_id: Valid IDs are returned by other methods which return location information. results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.available_dates()[source]

Return a list of available data sets.

http://data.police.uk/docs/method/crimes-street-dates/

Return:
List of strings indicating what years and months are available to query, returned from newest to oldest. String format is YYYY-MM
ukpolice.crime.categories(dataset_date=None)[source]

Returns a dictionary of valid categories for a given data set date.

http://data.police.uk/docs/method/crime-categories/

Arguments:
dataset_date = Year/Month to provide crime categories for
Returns:
Dictionary where the key is the unique identifier for the named crime category and the value is name of the crime category
ukpolice.crime.crime_detail(crime_identifier)[source]

Returns the outcomes (case history) for the specified crime.

http://data.police.uk/docs/method/outcomes-for-crime/

Arguments:
crime_identifier: 64-character identifier, available as the ‘id’ property of a Crime object.
Returns:
Outcomes #TODO - this and others
ukpolice.crime.last_updated()[source]

Show when crime data in the API was last updated

http://data.police.uk/docs/method/crime-last-updated/

Crime data in the API is updated once a month. Find out when it was last updated.

Returns:
String with the month of latest crime data in ISO format. The day is irrelevant and is only there to keep a standard formatted date.
ukpolice.crime.street_by_area(poly_points, results_month=None)[source]

Crimes at street-level within a custom area.

http://data.police.uk/docs/method/crime-street/

The street-level crimes returned in the API are only an approximation of where the actual crimes occurred, they are NOT the exact locations.

Arguments:
poly_points: List containing instances of Point results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.street_by_point(point, results_month=None)[source]

Crimes at street-level within a 1 mile radius of a single point

http://data.police.uk/docs/method/crime-street/

The street-level crimes returned in the API are only an approximation of where the actual crimes occurred, they are NOT the exact locations.

Arguments:
point: Instance of geopy.Point results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.street_level_availability(reverse_order=False)[source]

Return a list of available data sets.

http://data.police.uk/docs/method/crimes-street-dates/

Returns:
List of date data containing Year and month of all available street level crime data in ISO format. Ordered from most recent [0] to oldest [n], unless reverse is set to True
ukpolice.crime.street_outcomes_by_area(poly_points, results_month=None)[source]

Outcomes at street-level at a specific location

http://data.police.uk/docs/method/outcomes-at-location/

Note: Outcomes are not available for the Police Service of Northern Ireland.

Arguments:
location_id: Valid IDs are returned by other methods which return location information. results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.street_outcomes_by_id(location_id, results_month=None)[source]

Outcomes at street-level at a specific location

http://data.police.uk/docs/method/outcomes-at-location/

Note: Outcomes are not available for the Police Service of Northern Ireland.

Arguments:
location_id: Valid IDs are returned by other methods which return location information. results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.street_outcomes_by_point(point, results_month=None)[source]

Outcomes at street-level at a specific location

http://data.police.uk/docs/method/outcomes-at-location/

Note: Outcomes are not available for the Police Service of Northern Ireland.

Arguments:
location_id: Valid IDs are returned by other methods which return location information. results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects
ukpolice.crime.with_no_location(crime_category, force, results_month=None)[source]

Returns a list of crimes where the responsible force hasn’t specified a location.

http://data.police.uk/docs/method/crimes-no-location/

Arguments:
crime_category: Valid string from categories() force: Instance of Force object results_month: string in the format YYYY-MM
Returns:
List of instances of Crime objects

exceptions Module

exception ukpolice.exceptions.ForceNotFoundException(name)[source]

Bases: exceptions.Exception

__init__(name)[source]
exception ukpolice.exceptions.InvalidApiDateException(excepted_date)[source]

Bases: exceptions.Exception

__init__(excepted_date)[source]
exception ukpolice.exceptions.NeighbourhoodNotFoundException(name)[source]

Bases: exceptions.Exception

__init__(name)[source]
exception ukpolice.exceptions.NoJSON[source]

Bases: exceptions.Exception

exception ukpolice.exceptions.TooManyCrimesException[source]

Bases: exceptions.Exception

police Module

class ukpolice.police.Force(json_object)[source]

Provides access to Police Force information and the neighbourhoods they are responsible for

Note

This class should never be initiated directly. It should be returned from police modules

__init__(json_object)[source]
description[source]

Description of the force

engagement_methods[source]

Ways to keep informed

Returns:List – Returns a list of objects.
get_neighbourhood_by_id(neighbourhood_id)[source]
id[source]

Unique force identifier

name[source]

Force name

neighbourhoods[source]
phone[source]

Force telephone number

url[source]

Force website URL

class ukpolice.police.Neighbourhood(neighbourhood_name, neighbourhood_id, force_id)[source]

Provides access to neighbourhood information and contact details

Note

This class should never be initiated directly. It should be returned from Police.Force

__init__(neighbourhood_name, neighbourhood_id, force_id)[source]
Parameters:
  • neighbourhood_name (str.) – Name of neighbourhood.
  • neighbourhood_id (str.) – Unique ID of neighbourhood.
  • force_id (str.) – Police force associated with this neighbourhood.
boundary[source]

URL for the neighbourhood’s boundary in KML format

centre[source]

Centre point locator for the neighbourhood.

This may not be exactly in the centre of the neighbourhood

Returns:Point – Returns an instance of geopy.Point
description[source]

Description of the neighbourhood

email[source]

Email address to get in touch with the neighbourhood officers

events[source]

Return police event detail

id[source]

Unique ID for the neighbourhood

Links relevant to the neighbourhood.

Returns:List – Returns a list of objects with keys ‘url’, ‘title’ and ‘description’ [optional].
locations[source]

Any associated locations with the neighbourhood, e.g. police stations

Returns:List – Returns a list of objects.
message[source]

An introduction message for the neighbourhood

name[source]

Name of the neighbourhood

people[source]

Names of people involved

phone[source]

Phone number to get in touch with the neighbourhood officers

population[source]

Population for the neighbourhood

url[source]

URL for the neighbourhood on the Force’s website

ukpolice.police.get_all_forces()[source]

A list of all the police forces available via the API. The function returns a dictionary with the “Unique Force identifier” as key and a Force object as the value. The unique force identifier should be used in requests for force-specific data via other methods.

ukpolice.police.get_force_by_id(unique_force_identifier)[source]

Return a Force instance which corresponds to the supplied unique force identifier. Returns None if no instance is found

Parameters:unique_force_identifier (str.) – Unique Force identifier of the police force.
ukpolice.police.get_force_by_name(force_name)[source]

Return a Force instance which corresponds to the supplied name. Raise ForceNotFoundException if no instance is found

Parameters:force_name (str.) – Name of the police force.
ukpolice.police.get_force_by_point(point)[source]

Find the police force for a particular area. Returns an instance of a Force object

Parameters:point (geopy.Point instance) – Point for which the responsible police force should be returned
ukpolice.police.get_neighbourhood_by_point(point)[source]

Find the neighbourhood policing team responsible for a particular area. Returns an instance of a Neighbourhood object

Parameters:point (geopy.Point instance) – Point for which the responsible police force should be returned
ukpolice.police.list_all_force_ids()[source]

A list of all the police forces available via the API. The function returns a list with the “Unique Force identifier”. The unique force identifier should be used in requests for force-specific data via other methods.

service Module

class ukpolice.service.Street(id, name)[source]
__init__(id, name)[source]
id[source]
name[source]
ukpolice.service.fetch_data(url, **kwargs)[source]
ukpolice.service.fetch_json(url, **kwargs)[source]