Welcome to ukpolice’s documentation!¶
Contents:
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
- 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
- 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.InvalidApiDateException(excepted_date)[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
- 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.
- 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
- links[source]¶
Links relevant to the neighbourhood.
Returns: List – Returns a list of objects with keys ‘url’, ‘title’ and ‘description’ [optional].
- 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