Documentation Build Status Coverage Status Go Report Card

ukpolice is a Go client library for accessing the api


import ""

Construct a new ukpolice client, then use the various services on the client to access different parts of the API. It is recommended to pass in a http.Client with a longer timeout than default as some responses from the API can take over 60 seconds.

For example:

customClient := http.Client{Timeout: time.Second * 120}
	client := ukpolice.NewClient(&customClient))

// list all available data sets.
available, _, err := client.Availability.GetAvailabilityInfo(context.Background())

Some API methods have optional parameters that can be passed. For example:

searches, _, err := client.StopAndSearch.GetStopAndSearchesByForce(context.Background(),
        ukpolice.WithDate("2018-01"), ukpolice.WithForce("west-midlands"))

Rate Limiting

The api sets a rate limit of 15 requests per second. This limit is adhered to automatically by the package.


Contributions are always welcome.




View Source
const (
	// DefaultBaseURL is the URL of the API
	DefaultBaseURL = ""
	// DefaultUserAgent is the value to use in the User-Agent header if none
	// has been explicitly configured.
	DefaultUserAgent = "go-ukpolice"
	// RequestLimit is set to the rate limit of the api
	RequestLimit = 15
	// BurstLimit is set to the single second burst limit of the
	// api.
	BurstLimit = 30


This section is empty.


func Bool

func Bool(v bool) *bool

    Bool is a helper function that allocates a new bool value to store v and returns a pointer to it.

    func Float64

    func Float64(v float64) *float64

      Float64 is a helper function that allocates a new float64 value to store v and returns a pointer to it.

      func Int

      func Int(v int) *int

        Int is a helper function that allocates a new int value to store v and returns a pointer to it.

        func Int64

        func Int64(v int64) *int64

          Int64 is a helper function that allocates a new int64 value to store v and returns a pointer to it.

          func String

          func String(v string) *string

            String is a helper function that allocates a new string value to store v and returns a pointer to it.

            func Stringify

            func Stringify(message interface{}) string

              Stringify attempts to create a reasonable string representation of types returned by the API. It does things like resolve pointers to their values and omits struct fields with nil values.


              type AvailabilityInfo

              type AvailabilityInfo struct {
              	Date          string   `json:"date,omitempty"`
              	StopAndSearch []string `json:"stop-and-search,omitempty"`

                AvailabilityInfo holds information about data availability. Date is returned as a string not time.Time.

                func (AvailabilityInfo) String

                func (a AvailabilityInfo) String() string

                type AvailabilityService

                type AvailabilityService service

                  AvailabilityService handles communication with the availability related method of the API

                  func (*AvailabilityService) GetAvailabilityInfo

                  func (a *AvailabilityService) GetAvailabilityInfo(ctx context.Context) ([]AvailabilityInfo, *Response, error)

                    GetAvailabilityInfo returns information about data availability.

                    type Client

                    type Client struct {
                    	// BaseURL for API requests
                    	BaseURL *url.URL
                    	// UserAgent for communicating with the API
                    	UserAgent string
                    	// Services used for talking to different parts of the API
                    	Availability  *AvailabilityService
                    	Force         *ForceService
                    	Crime         *CrimeService
                    	Neighborhood  *NeighbourhoodService
                    	StopAndSearch *StopAndSearchService
                    	// contains filtered or unexported fields

                      Client manages communication with the API

                      func NewClient

                      func NewClient(httpClient *http.Client) *Client

                        NewClient returns a new API client. If a nil httpClient is provided, http.DefaultClient will be used.

                        It is recommended to pass in a http.Client with a longer timeout than default as some responses from the API (particularly when querying for Metropolitan police data) can take over 60 seconds. e.g http.Client{Timeout: time.Second * 120}

                        func (*Client) Do

                        func (api *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*Response, error)

                          Do carries out a request and stores the result in v.

                          func (*Client) NewRequest

                          func (api *Client) NewRequest(method, url string, body interface{}) (*http.Request, error)

                            NewRequest creates an API request. An url relative to the BaseURL of the client is provided. No request body is required for interaction with this API

                            type Crime

                            type Crime struct {
                            	Category        string            `json:"category,omitempty"`
                            	LocationType    string            `json:"location_type,omitempty"`
                            	Location        Location          `json:"location,omitempty"`
                            	Context         string            `json:"context,omitempty"`
                            	OutcomeStatus   map[string]string `json:"outcome_status,omitempty"`
                            	PersistentID    string            `json:"persistent_id,omitempty"`
                            	ID              uint              `json:"id,omitempty"`
                            	LocationSubtype string            `json:"location_subtype,omitempty"`
                            	Month           string            `json:"month,omitempty"`

                              Crime holds information about individual crimes recorded.

                              func (Crime) String

                              func (c Crime) String() string

                              type CrimeCategory

                              type CrimeCategory struct {
                              	URL  string `json:"url,omitempty"`
                              	Name string `json:"name,omitempty"`

                                CrimeCategory holds of valid categories.

                                type CrimeService

                                type CrimeService service

                                  CrimeService handles communication with the crime related method of the API.

                                  func (*CrimeService) GetCrimeCategories

                                  func (c *CrimeService) GetCrimeCategories(ctx context.Context, date Option) ([]CrimeCategory, *Response, error)

                                    GetCrimeCategories returns a list of valid crime categories for a given date.

                                    func (*CrimeService) GetCrimesAtLocation

                                    func (c *CrimeService) GetCrimesAtLocation(ctx context.Context, opts ...Option) ([]Crime, *Response, error)

                                      GetCrimesAtLocation 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.

                                      func (*CrimeService) GetCrimesWithNoLocation

                                      func (c *CrimeService) GetCrimesWithNoLocation(ctx context.Context, opts ...Option) ([]Crime, *Response, error)

                                        GetCrimesWithNoLocation returns a list of crimes associated to a specified police force that could not be mapped to a location. Force is mandatory. if no catergory is provided all-crime will be used as default

                                        func (*CrimeService) GetLastUpdated

                                        func (c *CrimeService) GetLastUpdated(ctx context.Context) (*Date, *Response, error)

                                          GetLastUpdated returns the date when the API was last updated.

                                          func (*CrimeService) GetSpecificOutcomes

                                          func (c *CrimeService) GetSpecificOutcomes(ctx context.Context, persistentID string) (*OutcomesForSpecificCrime, *Response, error)

                                            GetSpecificOutcomes returns the crime details and outcome details for a specific crime

                                            func (*CrimeService) GetStreetLevelCrimes

                                            func (c *CrimeService) GetStreetLevelCrimes(ctx context.Context, opts ...Option) ([]Crime, *Response, error)

                                              GetStreetLevelCrimes returns a list of street level crimes that satisfy the criteria provied by a variable of type CrimeQueryOptions. An empty slice indicates no data matching the query exists.

                                              func (*CrimeService) GetStreetLevelOutcomes

                                              func (c *CrimeService) GetStreetLevelOutcomes(ctx context.Context, opts ...Option) ([]Outcome, *Response, error)

                                                GetStreetLevelOutcomes returns Outcomes at street-level; either at a specific latitude or longitude, a specific locationID, or within a custom polygonal area.

                                                type Date

                                                type Date struct {
                                                	Date string `json:"date,omitempty" url:"date"`

                                                  Date represents a date in the format YYYY-MM

                                                  type EngagementMethods

                                                  type EngagementMethods struct {
                                                  	URL         string `json:"url,omitempty"`
                                                  	Description string `json:"description,omitempty"`
                                                  	Title       string `json:"title,omitempty"`

                                                    EngagementMethods holds information on a specific police force's social media.

                                                    type Force

                                                    type Force struct {
                                                    	ID          string              `json:"id,omitempty"`
                                                    	Name        string              `json:"name,omitempty"`
                                                    	Telephone   string              `json:"telephone,omitempty"`
                                                    	URL         string              `json:"url,omitempty"`
                                                    	Description string              `json:"description,omitempty"`
                                                    	Engagement  []EngagementMethods `json:"engagement_methods,omitempty"`

                                                      Force holds information about a police force

                                                      func (Force) String

                                                      func (f Force) String() string

                                                      type ForceService

                                                      type ForceService service

                                                        ForceService handles communication with the force related method of the API

                                                        func (*ForceService) GetForceDetails

                                                        func (f *ForceService) GetForceDetails(ctx context.Context, force string) (Force, *Response, error)

                                                          GetForceDetails returns more information about the provided force

                                                          func (*ForceService) GetForces

                                                          func (f *ForceService) GetForces(ctx context.Context) ([]Force, *Response, error)

                                                            GetForces returns a slice containing all available police forces.

                                                            func (*ForceService) GetPeople

                                                            func (f *ForceService) GetPeople(ctx context.Context, force string) ([]SeniorOfficer, *Response, error)

                                                              GetPeople returns a slice containing details of the senior police officers of the requested police force.

                                                              type Location

                                                              type Location struct {
                                                              	// Universal
                                                              	Latitude  string `json:"latitude,omitempty" db:"latitude"`
                                                              	Longitude string `json:"longitude,omitempty" db:"longitude"`
                                                              	// Used by Crime Methods
                                                              	Street struct {
                                                              		ID   uint   `json:"id,omitempty" db:"streetid"`
                                                              		Name string `json:"name,omitempty" db:"streetname"`
                                                              	} `json:"street,omitempty"`
                                                              	// Used by Neighbourhood methods
                                                              	Name        string `json:"name,omitempty"`
                                                              	Postcode    string `json:"postcode,omitempty"`
                                                              	Address     string `json:"address,omitempty"`
                                                              	Type        string `json:"type,omitempty"`
                                                              	Description string `json:"description,omitempty"`

                                                                Location holds location information shared by multiple methods.

                                                                type Neighbourhood

                                                                type Neighbourhood struct {
                                                                	ForceURL       string              `json:"url_force,omitempty"`
                                                                	ContactDetails map[string]string   `json:"contact_details,omitempty"`
                                                                	Name           string              `json:"name,omitempty"`
                                                                	Links          []map[string]string `json:"links,omitempty"`
                                                                	Centre         Location            `json:"centre,omitempty"`
                                                                	Locations      []Location          `json:"locations,omitempty"`
                                                                	Description    string              `json:"description,omitempty"`
                                                                	ID             string              `json:"id,omitempty"`
                                                                	Population     string              `json:"population,omitempty"`
                                                                	// Used by LocateNeighbourhood
                                                                	Force         string `json:"force,omitempty"`
                                                                	Neighbourhood string `json:"neighbourhood,omitempty"`

                                                                  Neighbourhood holds details of neighbourhoods.

                                                                  func (Neighbourhood) String

                                                                  func (n Neighbourhood) String() string

                                                                  type NeighbourhoodEvent

                                                                  type NeighbourhoodEvent struct {
                                                                  	ContactDetails map[string]string `json:"contact_details,omitempty"`
                                                                  	Description    string            `json:"description,omitempty"`
                                                                  	Title          string            `json:"title,omitempty"`
                                                                  	Address        string            `json:"address,omitempty"`
                                                                  	Type           string            `json:"type,omitempty"`
                                                                  	StartDate string `json:"start_date,omitempty"`
                                                                  	EndDate   string `json:"end_date,omitempty"`

                                                                    NeighbourhoodEvent holds details of neighbourhood events.

                                                                    func (NeighbourhoodEvent) String

                                                                    func (n NeighbourhoodEvent) String() string

                                                                    type NeighbourhoodPriorities

                                                                    type NeighbourhoodPriorities struct {
                                                                    	Action string `json:"action,omitempty"`
                                                                    	Issue  string `json:"issue,omitempty"`
                                                                    	IssueDate  string `json:"issue-date,omitempty"`
                                                                    	ActionDate string `json:"action-date,omitempty"`

                                                                      NeighbourhoodPriorities holds details of neighbourhood priorities.

                                                                      func (NeighbourhoodPriorities) String

                                                                      func (n NeighbourhoodPriorities) String() string

                                                                      type NeighbourhoodService

                                                                      type NeighbourhoodService service

                                                                        NeighbourhoodService handles communication with the neighbourhood related method of the API.

                                                                        func (*NeighbourhoodService) GetNeighbourhoodBoundary

                                                                        func (n *NeighbourhoodService) GetNeighbourhoodBoundary(ctx context.Context, force, NeighbourhoodID string) ([]Location, *Response, error)

                                                                          GetNeighbourhoodBoundary returns a list of latitude/longitude pairs that make up the boundary of a neighbourhood.

                                                                          func (*NeighbourhoodService) GetNeighbourhoodEvents

                                                                          func (n *NeighbourhoodService) GetNeighbourhoodEvents(ctx context.Context, force, NeighbourhoodID string) ([]NeighbourhoodEvent, *Response, error)

                                                                            GetNeighbourhoodEvents returns a list of events information for a given force and neighbourhood.

                                                                            func (*NeighbourhoodService) GetNeighbourhoodPriorities

                                                                            func (n *NeighbourhoodService) GetNeighbourhoodPriorities(ctx context.Context, force, NeighbourhoodID string) ([]NeighbourhoodPriorities, *Response, error)

                                                                              GetNeighbourhoodPriorities returns a list of priorities for a given force and neighbourhood

                                                                              func (*NeighbourhoodService) GetNeighbourhoodTeam

                                                                              func (n *NeighbourhoodService) GetNeighbourhoodTeam(ctx context.Context, force, NeighbourhoodID string) ([]NeighbourhoodTeam, *Response, error)

                                                                                GetNeighbourhoodTeam returns a list of team information for a given force and neighbourhood.

                                                                                func (*NeighbourhoodService) GetNeighbourhoods

                                                                                func (n *NeighbourhoodService) GetNeighbourhoods(ctx context.Context, force string) ([]Neighbourhood, *Response, error)

                                                                                  GetNeighbourhoods returns a the neighbourhood details for a given police force.

                                                                                  func (*NeighbourhoodService) GetSpecificNeighbourhood

                                                                                  func (n *NeighbourhoodService) GetSpecificNeighbourhood(ctx context.Context, force, ID string) (*Neighbourhood, *Response, error)

                                                                                    GetSpecificNeighbourhood returns the details of a specific neighbourhood given a police force and neighbourhood ID

                                                                                    func (*NeighbourhoodService) LocateNeighbourhood

                                                                                    func (n *NeighbourhoodService) LocateNeighbourhood(ctx context.Context, lat, long string) (*Neighbourhood, *Response, error)

                                                                                      LocateNeighbourhood returns the neighbourhood policing team responsible for a given latitude and longitude

                                                                                      type NeighbourhoodTeam

                                                                                      type NeighbourhoodTeam struct {
                                                                                      	Bio            string            `json:"bio,omitempty"`
                                                                                      	ContactDetails map[string]string `json:"contact_details,omitempty"`
                                                                                      	Name           string            `json:"name,omitempty"`
                                                                                      	Rank           string            `json:"rank,omitempty"`

                                                                                        NeighbourhoodTeam holds details of neighbourhood teams.

                                                                                        func (NeighbourhoodTeam) String

                                                                                        func (n NeighbourhoodTeam) String() string

                                                                                        type Option

                                                                                        type Option func(*url.Values)

                                                                                          Option specifies parameters to various methods that support multiple variable choices.

                                                                                          func WithCrimeCategory

                                                                                          func WithCrimeCategory(category string) Option

                                                                                            WithCrimeCategory sets provided crime category URL parameters.

                                                                                            func WithDate

                                                                                            func WithDate(date string) Option

                                                                                              WithDate sets provided date URL parameters.

                                                                                              func WithForce

                                                                                              func WithForce(force string) Option

                                                                                                WithForce sets provided force URL parameters.

                                                                                                func WithLatLong

                                                                                                func WithLatLong(latitude, longitude string) Option

                                                                                                  WithLatLong sets provided latitude and longitude URL parameters.

                                                                                                  func WithLocationID

                                                                                                  func WithLocationID(id string) Option

                                                                                                    WithLocationID sets provided locationID URL parameters.

                                                                                                    func WithPolygon

                                                                                                    func WithPolygon(poly string) Option

                                                                                                      WithPolygon sets provided polygon URL parameters.

                                                                                                      type Outcome

                                                                                                      type Outcome struct {
                                                                                                      	Category struct {
                                                                                                      		Code string `json:"code,omitempty"`
                                                                                                      		Name string `json:"name,omitempty"`
                                                                                                      	} `json:"category,omitempty"`
                                                                                                      	Date     string `json:"date,omitempty"`
                                                                                                      	PersonID uint   `json:"person_id,omitempty"`
                                                                                                      	Crime    Crime  `json:"crime,omitempty"`

                                                                                                        Outcome holds information on the outcome of a crime at street-level.

                                                                                                        type OutcomesForSpecificCrime

                                                                                                        type OutcomesForSpecificCrime struct {
                                                                                                        	Crime    Crime     `json:"crime,omitempty"`
                                                                                                        	Outcomes []Outcome `json:"outcomes,omitempty"`

                                                                                                          OutcomesForSpecificCrime holds information returned about the outcomes of a specific crime.

                                                                                                          type Response

                                                                                                          type Response struct {

                                                                                                            Response is a API response. This wraps the standard http.Response returned from

                                                                                                            type Search struct {
                                                                                                            	ID                             int           `json:"id"`
                                                                                                            	AgeRange                       string        `json:"age_range"`
                                                                                                            	Type                           string        `json:"type"`
                                                                                                            	Gender                         string        `json:"gender"`
                                                                                                            	Outcome                        SearchOutcome `json:"outcome"`
                                                                                                            	InvolvedPerson                 bool          `json:"involved_person"`
                                                                                                            	SelfDefinedEthnicity           string        `json:"self_defined_ethnicity"`
                                                                                                            	OfficerDefinedEthnicity        string        `json:"officer_defined_ethnicity"`
                                                                                                            	DateTime                       time.Time     `json:"datetime"`
                                                                                                            	RemovalOfMoreThanOuterClothing bool          `json:"removal_of_more_than_outer_clothing"`
                                                                                                            	Location                       Location      `json:"location"`
                                                                                                            	Operation                      bool          `json:"operation"`
                                                                                                            	OperationName                  string        `json:"operation_name"`
                                                                                                            	OutcomeLinkedToObject          bool          `json:"outcome_linked_to_object_of_search"`
                                                                                                            	ObjectOfSearch                 string        `json:"object_of_search"`
                                                                                                            	Legislation                    string        `json:"legislation"`
                                                                                                            	// Force is not supplied natively by the API - if you want to record which
                                                                                                            	// force a search belongs to update this field after fetching.
                                                                                                            	Force string `json:"force"`

                                                                                                              Search holds information relating to individual stop and searches.

                                                                                                              func (Search) String

                                                                                                              func (s Search) String() string

                                                                                                              type SearchOutcome

                                                                                                              type SearchOutcome struct {
                                                                                                              	Desc           string `json:"outcome_desc"`
                                                                                                              	SearchHappened bool   `json:"searched"`

                                                                                                                SearchOutcome holds details of search outcomes. The 'outcome' result provided by the api returns both string and bool types, this struct and the custom UnmarshalJSON satisfy type security.

                                                                                                                func (SearchOutcome) String

                                                                                                                func (o SearchOutcome) String() string

                                                                                                                func (*SearchOutcome) UnmarshalJSON

                                                                                                                func (o *SearchOutcome) UnmarshalJSON(b []byte) error

                                                                                                                  UnmarshalJSON implements the json.Unmarshaller interface.

                                                                                                                  type SeniorOfficer

                                                                                                                  type SeniorOfficer struct {
                                                                                                                  	Bio            string            `json:"bio,omitempty"`
                                                                                                                  	ContactDetails map[string]string `json:"contact_details,omitempty"`
                                                                                                                  	Name           string            `json:"name,omitempty"`
                                                                                                                  	Rank           string            `json:"rank,omitempty"`

                                                                                                                    SeniorOfficer holds information on Senior Officers within a police force.

                                                                                                                    func (SeniorOfficer) String

                                                                                                                    func (so SeniorOfficer) String() string

                                                                                                                    type StopAndSearchService

                                                                                                                    type StopAndSearchService service

                                                                                                                      StopAndSearchService handles communication with the stop and search related method of the API.

                                                                                                                      func (*StopAndSearchService) GetStopAndSearchesByArea

                                                                                                                      func (s *StopAndSearchService) GetStopAndSearchesByArea(ctx context.Context, opts ...Option) ([]Search, *Response, error)

                                                                                                                        GetStopAndSearchesByArea returns stop and searches at street-level; either within a 1 mile radius of a single point, or within a custom area.

                                                                                                                        func (*StopAndSearchService) GetStopAndSearchesByForce

                                                                                                                        func (s *StopAndSearchService) GetStopAndSearchesByForce(ctx context.Context, opts ...Option) ([]Search, *Response, error)

                                                                                                                          GetStopAndSearchesByForce returns stop and searches reported by a given police force.

                                                                                                                          func (*StopAndSearchService) GetStopAndSearchesByLocation

                                                                                                                          func (s *StopAndSearchService) GetStopAndSearchesByLocation(ctx context.Context, opts ...Option) ([]Search, *Response, error)

                                                                                                                            GetStopAndSearchesByLocation returns stop and searches at a particular location.

                                                                                                                            func (*StopAndSearchService) GetStopAndSearchesWithNoLocation

                                                                                                                            func (s *StopAndSearchService) GetStopAndSearchesWithNoLocation(ctx context.Context, opts ...Option) ([]Search, *Response, error)

                                                                                                                              GetStopAndSearchesWithNoLocation returns stop and searches with no location provided for a given police force.