README
¶
Pathfinder
Pathfinder is small web service that takes the source and a list of destinations and returns a list of routes between source and each destination.
Installation
Requirements:
If you fulfil all of the above requirements, you can simply install pathfinder with below command.
$ go install git.sr.ht/~thinkofher/pathfinder/cmd/pathfinder@latest
Deployment
Current version uses fly.io for deployment and docker containers for packaging. If you want to deploy new version of pathfinder, simply execute below command.
$ flyctl deploy
Make sure that you have flyctl tool
installed.
You can reach test instance of pathfinder here.
Hacking
Install go compiler and clone whole repository with git.
$ git clone https://git.sr.ht/~thinkofher/pathfinder
$ cd pathfinder
Then introduce your changes and run server executable.
$ go run ./cmd/pathfinder
Now you can test your changes. Don't forget about configuration!
Configuration
pathfinder can be configured with environmental variables. Below you can find short description for each configuration variable being used by pathfinder.
PATHFINDER_OSRM_URL
URL for OSRM API service. Example value is: https://router.project-osrm.org. There is no default value. Without specifying OSRM url, pathfinder won't work correctly.
PATHFINDER_ADDR
TCP/IP address for pathfinder to listen to. Default value is 0.0.0.0:8080.
API
Default interface for communicating with pathfinder is HTTP JSON API.
GET /routes
Endpoint takes the source and a list of destinations and returns a list of routes between source and each destination. Both source and destination are defined as a pair of latitude and longitude. The returned list of routes is sorted by driving time and distance (if time is equal).
Parameters
/routes requires client to provide two URL query parameters.
src- single value with source position coordinates. Example value:13.388860,52.517037.dst- multiple values for destination coordinates. Example value:13.428555,52.523219.
Response
Successful API call.
Example JSON output with full request.
GET /routes?src=13.388860,52.517037&dst=13.397634,52.529407&dst=13.428555,52.523219
{
"source": {
"long": 13.38886,
"lat": 52.517037
},
"routes": [
{
"destination": {
"long": 13.397634,
"lat": 52.529407
},
"duration": 253.6,
"distance": 1884.7
},
{
"destination": {
"long": 13.428555,
"lat": 52.523219
},
"duration": 384.4,
"distance": 3795
}
]
}
Some input parameter is invalid. See error message for more information.
Example JSON output.
{
"error": "Invalid string format for coordinates."
}
Example JSON output.
{
"error": "Internal server error. Please, try again later."
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInternalServerHTTPError = &JSONError{ Message: "Internal server error, please try again later.", Wrapped: errors.New("internal server error"), Status: http.StatusInternalServerError, }
ErrInternalServerHTTPError is JSONError implementation for http Internal server error.
var ErrInvalidCoordinatesFmt = errors.New("invalid coordinates format")
Functions ¶
func RoutesHandler ¶
func RoutesHandler(router Router) http.HandlerFunc
RoutesHandler is HTTP handler which return list of routes between source and each destination.
Source is provided with "src" single query parameter and destinations are provided with "dst" multiple query parameters.
Both source and destinations should implement following structure:
long,lat
Where long is longitude and lat is latitude.
Example source (or any destination) value:
13.388860,52.517037
Types ¶
type Coordinates ¶
type Coordinates struct {
// Longitude is a geographic coordinate that specifies the
// east-west position of a point on the Earth's surface.
Longitude float64 `json:"long"`
// Latitude is a geographic coordinate that specifies the
// north-south position of a point on the Earth's surface.
Latitude float64 `json:"lat"`
}
Coordinates, composed from longitude and latitude, are the units that represent the coordinates at geographic coordinate system.
func CoordinatesFromString ¶
func CoordinatesFromString(s string) (*Coordinates, error)
CoordinatesFromString parses coordinates values from string representation of longitude and latitude.
func (Coordinates) String ¶
func (d Coordinates) String() string
String implements fmt.Stringer interface. It returns formal representation of Longitude and Latitude where both values are separated by comma and Longitude is the first one.
type JSONError ¶
type JSONError struct {
// Wrapped error value.
Wrapped error
// Message is safe error message, that can be shown to the client.
Message string
// Status is http status header code.
Status int
}
JSONError is http JSON API error with http.Handler implementation.
type OSRMClient ¶
type OSRMClient struct {
// ServiceURL is url of OSRM service.
ServiceURL string
// Client is HTTP client for OSRMClient API client used
// for sending HTTP requests.
Client *http.Client
}
OSRMClient is HTTP API client for OSRM service.
func (*OSRMClient) Routes ¶
func (c *OSRMClient) Routes(ctx context.Context, req RoutesRequest) (*OSRMRouteResponse, error)
Routes finds the fastest route between coordinates in the supplied order.
See http://project-osrm.org/docs/v5.24.0/api/#route-service for more help.
type OSRMRoute ¶
type OSRMRoute struct {
// Duration is the estimated travel time, in float
// number of seconds.
Duration float64 `json:"duration"`
// Distance traveled by the route, in float meters.
Distance float64 `json:"distance"`
}
OSRMRoute represents a route through (potentially multiple) waypoints.
type OSRMRouteResponse ¶
type OSRMRouteResponse struct {
// Code is "Ok" if the request was successful.
Code string `json:"code"`
// Routes is an array of Route objects, ordered by
// descending recommendation rank.
Routes []OSRMRoute `json:"routes"`
}
OSRMRouteResponse of routes OSRM endpoint.
type Route ¶
type Route struct {
// Destination holds coordinates for destination position.
Destination Coordinates `json:"destination"`
// Duration is the estimated travel time, in float
// number of seconds.
Duration float64 `json:"duration"`
// Distance traveled by the route, in float meters.
Distance float64 `json:"distance"`
}
Route represents route's metadata for hypothetical source position.
type Router ¶
type Router interface {
// Routes return a list of routes between source and each destination.
Routes(ctx context.Context, src Coordinates, dst ...Coordinates) ([]Route, error)
}
Router takes the source and a list of destinations and returns a list of routes between source and each destination.
type RoutesRequest ¶
type RoutesRequest struct {
// Source is the beginning of the route.
Source Coordinates
// Destination is the end of the route.
Destination Coordinates
}
RoutesRequest holds arguments for Routes API call.
type RoutesSorter ¶
type RoutesSorter struct {
// Wrapped router interface. Its returned value will be
// sorted and returned further.
Wrapped Router
}
RoutesSorter is decorator which sorts routes returned by wrapped Router by the driving time and by the distance (if time is equal).
func (*RoutesSorter) Routes ¶
func (rs *RoutesSorter) Routes(ctx context.Context, src Coordinates, dst ...Coordinates) ([]Route, error)
Routes return a list of routes between source and each destination.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is main application interface. It exposes application's functionalities through HTTP protocol.
type Service ¶
type Service struct {
// Client is HTTP OSRM API client.
Client *OSRMClient
}
Service is entry point for all high level operations related to purpose of the whole application, which is finding routes between source and multiple destinations.
func (*Service) Routes ¶
func (s *Service) Routes(ctx context.Context, src Coordinates, dst ...Coordinates) ([]Route, error)
Routes return a list of routes between source and each destination.
Source Files
Directories