Police API Client (Python)¶

>>> from police_api import PoliceAPI
>>> api = PoliceAPI(user_agent='cops-and-robbers/9.9.9', timeout=60)

get_forces()¶

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

Return type:	list
Returns:	A list of Force objects (one for each police force in England, Wales and Northern Ireland).

get_neighbourhoods(force)¶

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

Parameters:	force (str or Force) – The force to get neighbourhoods for (either by ID or Force object)
Return type:	list
Returns:	A list of Neighbourhood objects (one for each Neighbourhood Policing Team in the given force).

get_neighbourhood(force, neighbourhood)¶

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 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)¶

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()¶

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()¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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 crimes which were snapped to the location with the specified ID in the given month.

get_crimes_no_location(force, date=None, category=None)¶

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 crimes which were reported in the given month, by the specified force, but which don’t have a location.

A police force in England, Wales or Northern Ireland. Uses the force API call.

>>> from police_api import PoliceAPI
>>> from police_api.forces import Force
>>> api = PoliceAPI()
>>> force = Force(api, id='leicestershire')
>>> force.name
'Leicestershire'

id¶

Type:	str

The force’s identifier (a slugified version of the name).

name¶

Type:	str

The full name of the force.

description¶

Type:	str

A short description of the force’s role.

url¶

Type:	str

The force’s website address.

telephone¶

Type:	str

The force’s main switchboard number. Usually set to '101' since the introduction of the national service.

engagement_methods¶

Type:	list

A list of dict, containing the keys url, type, description, and title.

>>> pprint(force.engagement_methods)
[{u'description': None,
  u'title': u'facebook',
  u'type': u'facebook',
  u'url': u'http://www.facebook.com/leicspolice'},
 {u'description': None,
  u'title': u'twitter',
  u'type': u'twitter',
  u'url': u'http://www.twitter.com/leicspolice'},
 {u'description': None,
  u'title': u'youtube',
  u'type': u'youtube',
  u'url': u'http://www.youtube.com/leicspolice'},
 {u'description': None,
  u'title': u'rss',
  u'type': u'rss',
  u'url': u'http://www.leics.police.uk/feeds/news/'},
 {u'description': None,
  u'title': u'telephone',
  u'type': u'telephone',
  u'url': u''},
 {u'description': None,
  u'title': u'flickr',
  u'type': u'flickr',
  u'url': u'http://www.flickr.com/photos/leicspolice-property'}]

neighbourhoods¶

Type:	list

A list of Neighbourhood objects (all the Neighbourhood Policing Teams in this force area).

senior_officers¶

Type:	list

A list of Force.SeniorOfficer objects.

A Neighbourhood Policing Team. Uses the neighbourhood API call.

>>> from police_api import PoliceAPI
>>> from police_api.forces import Force
>>> from police_api.neighbourhoods import Neighbourhood
>>> api = PoliceAPI()
>>> force = Force(api, id='leicestershire')
>>> neighbourhood = Neighbourhood(api, force=force, id='C04')
>>> neighbourhood.name
'City Centre Neighbourhood'

id¶

Type:	str

The neighbourhood’s identifier (usually a code, but can contain spaces).

name¶

Type:	str

The name of the NPT.

description¶

Type:	str

A description of the NPT’s area.

url_force¶

Type:	str

The URL for this NPT on the force’s website

population¶

Type:	str

An estimate of the number of people living within the NPT boundary.

centre¶

Type:	dict

The approximate centre point of the neighbourhood.

>>> neighbourhood.centre
{"latitude": "52.6268", "longitude": "-1.12621"}

links¶

Type:	list

A list of links relevant to this force.

>>> pprint(neighbourhood.links)
[{u'description': None,
  u'title': u'Leicester City Council',
  u'url': u'http://www.leicester.gov.uk/'},
 {u'description': None,
  u'title': u'Beaumont Leys LPU',
  u'url': u'http://leicspolice.wordpress.com/category/lpu-blogs/beaumont-leys/'}]

locations¶

Type:	list

A list of police stations in this NPT.

>>> pprint(neighbourhood.locations)
[{u'address': u'2 Beaumont Way\n, Leicester',
  u'description': None,
  u'latitude': None,
  u'longitude': None,
  u'name': u'Beaumont Leys',
  u'postcode': u'LE4 1DS',
  u'type': u'station'}]

contact_details¶

Type:	dict

Ways that this NPT can be contacted.

>>> pprint(neighbourhood.contact_details)
{u'email': u'beaumont.lpu@leicestershire.pnn.police.uk',
 u'facebook': u'http://www.facebook.com/leicestercitypolice',
 u'telephone': u'101',
 u'twitter': u'http://www.twitter.com/LPAbbey'}

officers¶

Type:	list

A list of Neighbourhood.Officer objects.

events¶

Type:	list

A list of Neighbourhood.Event objects.

priorities¶

Type:	list

A list of Neighbourhood.Priority objects.

boundary¶

Type:	list

A list of (lat, lng) coordinates representing the perimeter of this neighbourhood’s boundary.

>>> pprint(neighbourhood.boundary)
[(52.6235790036, -1.1433951806),
 (52.6235759765, -1.1432002292),
 ...
 (52.6241719477, -1.143313233),
 (52.6235790036, -1.1433951806)]

An individual crime. Uses the outcomes-for-crime API call.

id¶

Type:	int

This crime’s unique internal ID (not used elsewhere in the data or API).

persistent_id¶

Type:	str

This crime’s persistent ID, which is referenced by the outcomes data and in the CSV files. Not guaranteed to be unique.

month¶

Type:	str

The month that this crime was reported in (%m-%d).

category¶

Type:	CrimeCategory

The category of this crime.

location¶

Type:	Location

The anonymised location that this crime occurred closest to.

context¶

Type:	str

Additional data about this crime provided by the reporting force.

outcome_status¶

Type:	Crime.Outcome

The latest outcome to have been recorded for this crime.

outcomes¶

Type:	list

A list of Outcome objects for this crime.