Add examples, housekeeping

Author: qba73

README.md

@@ -40,6 +40,12 @@ if err != nil {
 }
 ```
 
+## Complete example programs
+
+You can see complete example programs which retrive coordinates and postal codes in the [examples](examples/) folder.
+
+- postal codes lookup example: [examples/postal](examples/postal/main.go)
+- coordinates lookup example: [examples/wikipedia](examples/wikipedia/main.go)
 
 
 ## Bugs and feature request

examples/postal/go.mod

@@ -0,0 +1,5 @@
+module example-postal
+
+go 1.19
+
+require github.com/qba73/geonames v0.0.2

examples/postal/go.sum

@@ -0,0 +1,3 @@
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/qba73/geonames v0.0.2 h1:MWYZ+YbG5uEdzFyG0ZMo0xLBU0jCQT/P2635Q2S598s=
+github.com/qba73/geonames v0.0.2/go.mod h1:2YIjYC03dZXrYz8D2OZCMRwGLKn/6qaSEJ0yPShv6E4=

examples/postal/main.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/qba73/geonames"
+)
+
+func main() {
+	// We exported valid "GEONAMES_USER" env var
+	geo, err := geonames.NewClient()
+	if err != nil {
+		panic(err)
+	}
+
+	codes, err := geo.GetPostCode("Fort William", "UK")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, c := range codes {
+		fmt.Printf("%+v\n", c)
+	}
+}

examples/wikipedia/go.mod

@@ -0,0 +1,5 @@
+module example-wikipedia
+
+go 1.19
+
+require github.com/qba73/geonames v0.0.2

examples/wikipedia/go.sum

@@ -0,0 +1,3 @@
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/qba73/geonames v0.0.2 h1:MWYZ+YbG5uEdzFyG0ZMo0xLBU0jCQT/P2635Q2S598s=
+github.com/qba73/geonames v0.0.2/go.mod h1:2YIjYC03dZXrYz8D2OZCMRwGLKn/6qaSEJ0yPShv6E4=

examples/wikipedia/main.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/qba73/geonames"
+)
+
+func main() {
+	// We exported valid "GEONAMES_USER" env var
+	geo, err := geonames.NewClient()
+	if err != nil {
+		panic(err)
+	}
+
+	codes, err := geo.GetPostCode("Fort William", "UK")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, c := range codes {
+		fmt.Printf("%+v\n", c)
+	}
+}

geonames.go

@@ -1,10 +1,12 @@
 package geonames
 
 import (
+	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
-	"net/url"
 	"os"
 	"time"
 )
@@ -91,24 +93,33 @@ func NewClient(options ...option) (*Client, error) {
 	return &c, nil
 }
 
-// makeURL knows how to create encoded URL with provided query parameters.
-func makeURL(base string, params url.Values) (string, error) {
-	b, err := url.Parse(base)
+func (c Client) get(url string, data interface{}) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
-		return "", fmt.Errorf("parsing base url, %w", err)
+		return fmt.Errorf("creating request: %w", err)
 	}
-	b.RawQuery = params.Encode()
-	return b.String(), nil
-}
+	res, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("sending GET request: %w", err)
+	}
+	defer res.Body.Close()
 
-// prepareGETRequest takes URL string and prepares HTTP Get request.
-func (c Client) prepareGETRequest(u string) (*http.Request, error) {
-	req, err := http.NewRequest(http.MethodGet, u, nil)
+	if res.StatusCode != http.StatusOK {
+		return fmt.Errorf("got response code: %v", res.StatusCode)
+	}
+
+	body, err := io.ReadAll(res.Body)
 	if err != nil {
-		return nil, err
+		return fmt.Errorf("reading response body: %w", err)
+	}
+
+	if err := json.Unmarshal(body, data); err != nil {
+		return fmt.Errorf("unmarshaling response body: %w", err)
 	}
-	req.Header = c.headers
-	return req, nil
+	return nil
 }
 
 type Position struct {

postal.go

@@ -1,9 +1,7 @@
 package geonames
 
 import (
-	"encoding/json"
 	"fmt"
-	"io"
 	"net/url"
 )
 
@@ -31,29 +29,13 @@ type PostalCode struct {
 
 // Get knows how to retrieve postal codes for the given place name and country code.
 func (c Client) GetPostCode(place, country string) ([]PostalCode, error) {
-	u, err := c.makePostalURL(place, country)
+	url, err := c.buildPostalURL(place, country)
 	if err != nil {
 		return nil, err
 	}
-
-	req, err := c.prepareGETRequest(u)
-	if err != nil {
-		return nil, err
-	}
-
-	res, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer res.Body.Close()
-
 	var pr postalResponse
-	data, err := io.ReadAll(res.Body)
-	if err != nil {
-		return nil, fmt.Errorf("reading response body %w", err)
-	}
-	if err := json.Unmarshal(data, &pr); err != nil {
-		return nil, fmt.Errorf("unmarshalling data, %w", err)
+	if err := c.get(url, &pr); err != nil {
+		return nil, err
 	}
 
 	var postalCodes []PostalCode
@@ -74,12 +56,18 @@ func (c Client) GetPostCode(place, country string) ([]PostalCode, error) {
 	return postalCodes, nil
 }
 
-func (c Client) makePostalURL(placeName, countryCode string) (string, error) {
-	prms := url.Values{
+func (c Client) buildPostalURL(placeName, countryCode string) (string, error) {
+	params := url.Values{
 		"placename": {placeName},
 		"country":   {countryCode},
 		"username":  {c.userName},
 	}
-	basePostal := fmt.Sprintf("%s/%s", c.baseURL, "postalCodeSearchJSON")
-	return makeURL(basePostal, prms)
+	basePostal := fmt.Sprintf("%s/postalCodeSearchJSON", c.baseURL)
+
+	u, err := url.Parse(basePostal)
+	if err != nil {
+		return "", fmt.Errorf("parsing base url for postal, %w", err)
+	}
+	u.RawQuery = params.Encode()
+	return u.String(), nil
 }

wikipedia.go

@@ -1,9 +1,7 @@
 package geonames
 
 import (
-	"encoding/json"
 	"fmt"
-	"io"
 	"net/url"
 	"strconv"
 )
@@ -39,33 +37,20 @@ type Geoname struct {
 
 // GetPlace retrives geo coordinates for given place name and country code.
 func (c Client) GetPlace(name, country string, maxResults int) ([]Geoname, error) {
-	u, err := c.makeWikiURL(name, country, maxResults)
-	if err != nil {
-		return nil, err
-	}
-	req, err := c.prepareGETRequest(u)
-	if err != nil {
-		return nil, err
+	if maxResults < 1 {
+		return nil, fmt.Errorf("invalid max results: %d", maxResults)
 	}
-
-	res, err := c.httpClient.Do(req)
+	url, err := c.buildWikiURL(name, country, maxResults)
 	if err != nil {
 		return nil, err
 	}
-	defer res.Body.Close()
-
-	data, err := io.ReadAll(res.Body)
-	if err != nil {
-		return nil, fmt.Errorf("reading response body %w", err)
-	}
 
 	var wr wikipediaResponse
-	if err := json.Unmarshal(data, &wr); err != nil {
-		return nil, fmt.Errorf("unmarshalling data, %w", err)
+	if err := c.get(url, &wr); err != nil {
+		return nil, err
 	}
 
 	var geonames []Geoname
-
 	for _, g := range wr.Geonames {
 		geoname := Geoname{
 			Summary:   g.Summary,
@@ -87,17 +72,19 @@ func (c Client) GetPlace(name, country string, maxResults int) ([]Geoname, error
 	return geonames, nil
 }
 
-func (c Client) makeWikiURL(place, country string, maxResults int) (string, error) {
-	if maxResults < 1 {
-		return "", fmt.Errorf("incorrect results limit: %q", maxResults)
-	}
-	prms := url.Values{
+func (c Client) buildWikiURL(place, country string, maxResults int) (string, error) {
+	params := url.Values{
 		"q":           []string{place},
 		"title":       []string{place},
 		"countryCode": []string{country},
 		"maxRows":     []string{strconv.Itoa(maxResults)},
 		"username":    []string{c.userName},
 	}
-	base := fmt.Sprintf("%s/%s", c.baseURL, "wikipediaSearchJSON")
-	return makeURL(base, prms)
+	baseWiki := fmt.Sprintf("%s/wikipediaSearchJSON", c.baseURL)
+	u, err := url.Parse(baseWiki)
+	if err != nil {
+		return "", fmt.Errorf("parsing wikipedia base url: %w", err)
+	}
+	u.RawQuery = params.Encode()
+	return u.String(), nil
 }