Add stop finder AP

README.md

@@ -4,13 +4,39 @@ Simple Go library wrapping VVS API
 
 ## Features
 - Journey search 
+- Station finder
 - Departure information
 - Arrival information
 
 ## Prerequisites
 - Go version >= 1.19
 
 ## Usage
+### Example: station finder
+```go
+package main
+
+import (
+    "github.com/ownerofglory/govvs"
+    "github.com/ownerofglory/govvs/station"
+)
+
+func main() {
+	req := govvs.StopFinderRequest{
+		Name: "Augustinum",
+		Type: "any",
+	}
+	res, err := govvs.GetStopFinder(req)
+
+	if err != nil {
+		// handle error ...
+	}
+
+	// process response
+	// ...
+}
+```
+
 ### Example: departure monitor
 ```go
 package main
@@ -24,7 +50,7 @@ func main() {
     stationName := station.HAUPTBAHNHOF_TIEF_STUTTGART
 
     // convert station name to station id (de:XXXXX:YYYY)
-    stationId, _ := station.NameToGlobalId(stationName)
+    stationId, _ := station.StationNameToGlobalId(stationName)
 
     req := govvs.DepartureRequest{
         StationId: stationId,
@@ -50,8 +76,8 @@ import (
 
 func main() {
     // convert station name to station id (de:XXXXX:YYYY)
-    origId, _ := station.NameToGlobalId(station.HAUPTBAHNHOF_TIEF_STUTTGART)
-    destId, _ := station.NameToGlobalId(station.FLUGHAFENMESSE_ECHTERDINGEN)
+    origId, _ := station.StationNameToGlobalId(station.HAUPTBAHNHOF_TIEF_STUTTGART)
+    destId, _ := station.StationNameToGlobalId(station.FLUGHAFENMESSE_ECHTERDINGEN)
 
     req := govvs.JourneyRequest{
 		OrigId: origId,

arrival/arrival.go

@@ -1,21 +1,21 @@
 package arrival
 
-import "github.com/ownerofglory/govvs/common"
+import "github.com/ownerofglory/govvs/vvscommon"
 
 type Arrival struct {
-	StopID       string             `json:"stopID"`
-	X            string             `json:"x"`
-	Y            string             `json:"y"`
-	MapName      string             `json:"mapName"`
-	Area         string             `json:"area"`
-	Platform     string             `json:"platform"`
-	PlatformName string             `json:"platformName,omitempty"`
-	StopName     string             `json:"stopName"`
-	NameWO       string             `json:"nameWO"`
-	Countdown    string             `json:"countdown"`
-	DateTime     common.DateTime    `json:"dateTime"`
-	RealDateTime common.DateTime    `json:"realDateTime"`
-	ServingLine  common.ServingLine `json:"servingLine"`
-	Operator     common.Operator    `json:"operator"`
-	Attrs        []common.Attr      `json:"attrs"`
+	StopID       string                `json:"stopID"`
+	X            string                `json:"x"`
+	Y            string                `json:"y"`
+	MapName      string                `json:"mapName"`
+	Area         string                `json:"area"`
+	Platform     string                `json:"platform"`
+	PlatformName string                `json:"platformName,omitempty"`
+	StopName     string                `json:"stopName"`
+	NameWO       string                `json:"nameWO"`
+	Countdown    string                `json:"countdown"`
+	DateTime     vvscommon.DateTime    `json:"dateTime"`
+	RealDateTime vvscommon.DateTime    `json:"realDateTime"`
+	ServingLine  vvscommon.ServingLine `json:"servingLine"`
+	Operator     vvscommon.Operator    `json:"operator"`
+	Attrs        []vvscommon.Attr      `json:"attrs"`
 }

departure/departure.go

@@ -1,24 +1,24 @@
 package departure
 
-import "github.com/ownerofglory/govvs/common"
+import "github.com/ownerofglory/govvs/vvscommon"
 
 type Departure struct {
-	StopID       string             `json:"stopID"`
-	X            string             `json:"x"`
-	Y            string             `json:"y"`
-	MapName      string             `json:"mapName"`
-	Area         string             `json:"area"`
-	Platform     string             `json:"platform"`
-	PlatformName string             `json:"platformName,omitempty"`
-	StopName     string             `json:"stopName"`
-	NameWO       string             `json:"nameWO"`
-	Countdown    string             `json:"countdown"`
-	DateTime     common.DateTime    `json:"dateTime"`
-	ServingLine  common.ServingLine `json:"servingLine"`
-	Operator     common.Operator    `json:"operator"`
-	StopInfos    *StopInfos         `json:"stopInfos,omitempty"`
-	LineInfos    interface{}        `json:"lineInfos,omitempty"`
-	TripInfos    interface{}        `json:"tripInfos,omitempty"`
+	StopID       string                `json:"stopID"`
+	X            string                `json:"x"`
+	Y            string                `json:"y"`
+	MapName      string                `json:"mapName"`
+	Area         string                `json:"area"`
+	Platform     string                `json:"platform"`
+	PlatformName string                `json:"platformName,omitempty"`
+	StopName     string                `json:"stopName"`
+	NameWO       string                `json:"nameWO"`
+	Countdown    string                `json:"countdown"`
+	DateTime     vvscommon.DateTime    `json:"dateTime"`
+	ServingLine  vvscommon.ServingLine `json:"servingLine"`
+	Operator     vvscommon.Operator    `json:"operator"`
+	StopInfos    *StopInfos            `json:"stopInfos,omitempty"`
+	LineInfos    interface{}           `json:"lineInfos,omitempty"`
+	TripInfos    interface{}           `json:"tripInfos,omitempty"`
 }
 
 type StopInfos struct {

journey/trip.go

@@ -1,6 +1,6 @@
 package journey
 
-import "github.com/ownerofglory/govvs/common"
+import "github.com/ownerofglory/govvs/vvscommon"
 
 type Leg struct {
 	Duration             int                `json:"duration"`
@@ -84,7 +84,7 @@ type Transportation struct {
 	Number           string                    `json:"number"`
 	Description      string                    `json:"description"`
 	Product          TransportationProduct     `json:"product"`
-	Operator         common.Operator           `json:"operator"`
+	Operator         vvscommon.Operator        `json:"operator"`
 	Destination      TransportationDestination `json:"destination"`
 	Properties       TransportationProperties  `json:"properties"`
 }
@@ -207,23 +207,6 @@ type TicketProperties struct {
 	TariffProductOption  []interface{} `json:"tariffProductOption"`
 }
 
-type ServerInfo struct {
-	ControllerVersion string  `json:"controllerVersion"`
-	ServerID          string  `json:"serverID"`
-	VirtDir           string  `json:"virtDir"`
-	ServerTime        string  `json:"serverTime"`
-	CalcTime          float64 `json:"calcTime"`
-	LogRequestId      string  `json:"logRequestId"`
-}
-
-type SystemMessage struct {
-	Type    string `json:"type"`
-	Module  string `json:"module"`
-	Code    int    `json:"code"`
-	Text    string `json:"text"`
-	SubType string `json:"subType"`
-}
-
 type Journey struct {
 	Rating        int           `json:"rating"`
 	IsAdditional  bool          `json:"isAdditional"`

request.go

@@ -23,6 +23,14 @@ const (
 
 	// ParamUseRealtime specifies whether to use real-time data. "1" for yes, "0" for no.
 	ParamUseRealtime = "useRealtime"
+
+	// ParamNameSF specifies the stop or location name for which stop finder information is requested.
+	// This parameter is used to identify the specific location or address the stop finder should search for.
+	ParamNameSF = "name_sf"
+
+	// ParamTypeSF specifies the type of location being searched for in the stop finder request.
+	// It defines the category of the location such as "any", "stop", "street", etc.
+	ParamTypeSF = "type_sf"
 )
 
 // Constants for VVS (Verkehrs- und Tarifverbund Stuttgart) API request parameters.
@@ -241,6 +249,28 @@ type DepartureRequest struct {
 	LangCode  *string
 }
 
+// StopFinderRequest represents the parameters required to request information about stops for a specific location.
+//
+// Fields:
+// - Name (string): The name of the stop or location for which stop information is requested.
+// - Type (string): The type of the location being queried (e.g., "any" to allow any type of location). This may correspond to station, locality, or stop types.
+// - CoordOutputFormat (string): Specifies the format of the coordinates in the response, commonly "EPSG:4326" for latitude and longitude.
+// - OutputFormat (string): Specifies the format of the response data, such as "rapidJSON".
+// - ServerInfo (*bool): Whether to include server information in the response. Set true for including it.
+// - Language (*string): The language for the response (e.g., "de" for German). If nil, the default language set by the API is used.
+// - UseRealtime (*bool): Whether to include real-time information in the response. If nil, the API's default behavior is used.
+//
+// This struct is used to encapsulate the parameters required to search for stops near a location.
+type StopFinderRequest struct {
+	Name              string
+	Type              string
+	CoordOutputFormat string
+	OutputFormat      string
+	ServerInfo        *bool
+	Language          *string
+	UseRealtime       *bool
+}
+
 // ReqParam represents an individual request parameter that can be included in API requests.
 //
 // Fields:
@@ -340,3 +370,14 @@ var defaultDepartureParams = map[string]string{
 	ParamOutputFormat:                    "json",
 	ParamCoordOutputFormat:               "WGS84[DD.ddddd]",
 }
+
+var defaultStopFinderParams = map[string]string{
+	ParamSpEncId:              "0",
+	ParamCoordOutputFormat:    "EPSG:4326",
+	ParamLanguage:             "de",
+	ParamLocationServerActive: "1",
+	ParamOutputFormat:         "rapidJSON",
+	ParamServerInfo:           "1",
+	ParamUseRealtime:          "1",
+	ParamTypeOrigin:           "any",
+}

response.go

@@ -2,71 +2,88 @@ package govvs
 
 import (
 	"github.com/ownerofglory/govvs/arrival"
-	"github.com/ownerofglory/govvs/common"
 	"github.com/ownerofglory/govvs/departure"
 	"github.com/ownerofglory/govvs/journey"
+	"github.com/ownerofglory/govvs/station"
+	"github.com/ownerofglory/govvs/vvscommon"
 )
 
 // ArrivalResponse encapsulates the response data for an API request querying arrival information.
 //
 // Fields:
-// - Parameters ([]Parameter): A list of parameters that were used in the request, providing context for the response.
-// - DM (DM): Detailed information about the requested destination, including metadata.
-// - Arr (Arr): Contains specific data related to the arrival query.
-// - DateTime (DateTime): The date and time information relevant to the arrival request.
-// - DateRange ([]DateRange): A list of date ranges applicable to the arrival information provided.
-// - Option (Option): Options that were applied to the arrival request, such as filters or search criteria.
-// - ServingLines (ServingLines): Information about the lines serving the queried station or location.
-// - ArrivalList ([]Arrival): A comprehensive list of arrivals matching the request criteria, including details about each arrival.
+// - Parameters ([]vvscommon.Parameter): A list of parameters that were used in the request, providing context for the response.
+// - DM (vvscommon.DM): Detailed information about the requested destination, including metadata.
+// - Arr (vvscommon.Arr): Contains specific data related to the arrival query.
+// - DateTime (vvscommon.DateTime): The date and time information relevant to the arrival request.
+// - DateRange ([]vvscommon.DateRange): A list of date ranges applicable to the arrival information provided.
+// - Option (vvscommon.Option): Options that were applied to the arrival request, such as filters or search criteria.
+// - ServingLines (vvscommon.ServingLines): Information about the lines serving the queried station or location.
+// - ArrivalList ([]arrival.Arrival): A comprehensive list of arrivals matching the request criteria, including details about each arrival.
 //
 // ArrivalResponse provides a structured format for interpreting the data returned from an arrival information request to the API.
 type ArrivalResponse struct {
-	Parameters   []common.Parameter  `json:"parameters"`
-	DM           common.DM           `json:"dm"`
-	Arr          common.Arr          `json:"arr"`
-	DateTime     common.DateTime     `json:"dateTime"`
-	DateRange    []common.DateRange  `json:"dateRange"`
-	Option       common.Option       `json:"option"`
-	ServingLines common.ServingLines `json:"servingLines"`
-	ArrivalList  []arrival.Arrival   `json:"arrivalList"`
+	Parameters   []vvscommon.Parameter  `json:"parameters"`
+	DM           vvscommon.DM           `json:"dm"`
+	Arr          vvscommon.Arr          `json:"arr"`
+	DateTime     vvscommon.DateTime     `json:"dateTime"`
+	DateRange    []vvscommon.DateRange  `json:"dateRange"`
+	Option       vvscommon.Option       `json:"option"`
+	ServingLines vvscommon.ServingLines `json:"servingLines"`
+	ArrivalList  []arrival.Arrival      `json:"arrivalList"`
 }
 
 // DepartureResponse encapsulates the response data for an API request querying departure information.
 //
 // Fields:
-// - Parameters ([]Parameter): A list of parameters that were used in the request, providing insight into the response context.
-// - DM (DM): Provides detailed information about the destination or station from which departures are being queried.
-// - Arr (Arr): Contains specific data related to the departure query.
-// - DateTime (DateTime): The date and time information pertinent to the departure request.
-// - DateRange ([]DateRange): A series of date ranges that are relevant to the departure information provided.
-// - Option (Option): Options applied to the departure request, such as filters or search criteria.
-// - ServingLines (ServingLines): Details about the lines that serve the queried station or location.
-// - DepartureList ([]Departure): A detailed list of departures that match the request criteria, including information about each departure.
+// - Parameters ([]vvscommon.Parameter): A list of parameters that were used in the request, providing insight into the response context.
+// - DM (vvscommon.DM): Provides detailed information about the destination or station from which departures are being queried.
+// - Arr (vvscommon.Arr): Contains specific data related to the departure query.
+// - DateTime (vvscommon.DateTime): The date and time information pertinent to the departure request.
+// - DateRange ([]vvscommon.DateRange): A series of date ranges that are relevant to the departure information provided.
+// - Option (vvscommon.Option): Options applied to the departure request, such as filters or search criteria.
+// - ServingLines (vvscommon.ServingLines): Details about the lines that serve the queried station or location.
+// - DepartureList ([]departure.Departure): A detailed list of departures that match the request criteria, including information about each departure.
 //
 // DepartureResponse offers a structured approach to understanding the data returned from a departure information request to the API.
 type DepartureResponse struct {
-	Parameters    []common.Parameter    `json:"parameters"`
-	DM            common.DM             `json:"dm"`
-	Arr           common.Arr            `json:"arr"`
-	DateTime      common.DateTime       `json:"dateTime"`
-	DateRange     []common.DateRange    `json:"dateRange"`
-	Option        common.Option         `json:"option"`
-	ServingLines  common.ServingLines   `json:"servingLines"`
-	DepartureList []departure.Departure `json:"departureList"`
+	Parameters    []vvscommon.Parameter  `json:"parameters"`
+	DM            vvscommon.DM           `json:"dm"`
+	Arr           vvscommon.Arr          `json:"arr"`
+	DateTime      vvscommon.DateTime     `json:"dateTime"`
+	DateRange     []vvscommon.DateRange  `json:"dateRange"`
+	Option        vvscommon.Option       `json:"option"`
+	ServingLines  vvscommon.ServingLines `json:"servingLines"`
+	DepartureList []departure.Departure  `json:"departureList"`
 }
 
 // JourneyResponse represents the data structure for a response to a journey planning request.
 //
 // Fields:
-// - ServerInfo (ServerInfo): Contains metadata about the server that processed the request, including version and performance metrics.
+// - ServerInfo (vvscommon.ServerInfo): Contains metadata about the server that processed the request, including version and performance metrics.
 // - Version (string): The version of the API or data format used to generate the response.
-// - SystemMessages ([]SystemMessage): A list of system messages related to the request, which may include warnings or errors encountered during processing.
-// - Journeys ([]Journey): A list of journey options that match the request criteria, providing comprehensive details about each available journey.
+// - SystemMessages ([]vvscommon.SystemMessage): A list of system messages related to the request, which may include warnings or errors encountered during processing.
+// - Journeys ([]journey.Journey): A list of journey options that match the request criteria, providing comprehensive details about each available journey.
 //
 // JourneyResponse provides a detailed overview of journey options between specified points, including routes, timings, and other relevant information as per the request parameters.
 type JourneyResponse struct {
-	ServerInfo     journey.ServerInfo      `json:"serverInfo"`
-	Version        string                  `json:"version"`
-	SystemMessages []journey.SystemMessage `json:"systemMessages"`
-	Journeys       []journey.Journey       `json:"journeys"`
+	ServerInfo     vvscommon.ServerInfo      `json:"serverInfo"`
+	Version        string                    `json:"version"`
+	SystemMessages []vvscommon.SystemMessage `json:"systemMessages"`
+	Journeys       []journey.Journey         `json:"journeys"`
+}
+
+// StopFinderResponse represents the data structure for a response to a stop finder request.
+//
+// Fields:
+// - Version (string): The version of the API or data format used to generate the response.
+// - ServerInfo (vvscommon.ServerInfo): Contains metadata about the server that processed the request, including version, server ID, and processing time metrics.
+// - SystemMessages ([]vvscommon.SystemMessage): A list of system messages related to the request, such as status messages or warnings.
+// - Locations ([]station.Location): A list of locations that match the stop finder request, each containing details about the location, including nearby public transport stops.
+//
+// StopFinderResponse provides a detailed overview of locations and associated public transport stops that match the requested input, along with relevant server information and system messages.
+type StopFinderResponse struct {
+	Version        string                    `json:"version"`
+	ServerInfo     vvscommon.ServerInfo      `json:"serverInfo"`
+	SystemMessages []vvscommon.SystemMessage `json:"systemMessages"`
+	Locations      []station.Location        `json:"locations"`
 }