ukpolice

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 29, 2019 License: BSD-3-Clause Imports: 10 Imported by: 4

README

ukpolice

Documentation Build Status Coverage Status Go Report Card

ukpolice is a Go client library for accessing the data.police.uk api

Usage

import "github.com/tjcain/ukpolice"

Construct a new ukpolice client, then use the various services on the client to access different parts of the data.police.uk 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 data.police.uk api sets a rate limit of 15 requests per second. This limit is adhered to automatically by the package.

Contributing

Contributions are always welcome.

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL is the URL of the data.police.uk API
	DefaultBaseURL = "https://data.police.uk/api/"
	// 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 data.police.uk api
	RequestLimit = 15
	// BurstLimit is set to the single second burst limit of the
	// data.police.uk api.
	BurstLimit = 30
)

Variables

This section is empty.

Functions

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 data.police.uk API. It does things like resolve pointers to their values and omits struct fields with nil values.

Types

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 data.police.uk 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 data.police.uk API
	UserAgent string

	// Services used for talking to different parts of the data.police.uk API
	Availability  *AvailabilityService
	Force         *ForceService
	Crime         *CrimeService
	Neighborhood  *NeighbourhoodService
	StopAndSearch *StopAndSearchService
	// contains filtered or unexported fields
}

Client manages communication with the data.police.uk API

func NewClient 

func NewClient(httpClient *http.Client) *Client

NewClient returns a new data.police.uk 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 data.police.uk 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 data.police.uk 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 data.police.uk 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 {
	*http.Response
}

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

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 data.police.uk 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 data.police.uk 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.