geocodingmeteo

Documentation

Overview

Package geocodingmeteo is the library behind the geocodingmeteo command line: the HTTP client, request shaping, and the typed data models for the Open-Meteo Geocoding API.

The Client sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)
  • func (c *Client) Search(ctx context.Context, name string, count int, language string) ([]*Location, error)
• type Config
  • func DefaultConfig() Config
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Location

Constants

const DefaultUserAgent = "geocodingmeteo/dev (+https://github.com/tamnd/geocodingmeteo-cli)"

DefaultUserAgent identifies the client to Open-Meteo. A real, honest User-Agent is both polite and the thing most likely to keep you unblocked.

const Host = "geocoding-api.open-meteo.com"

Host is the geocoding API hostname, used as the URI driver scheme host.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	BaseURL   string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to the Open-Meteo Geocoding API over HTTPS.

func NewClient

func NewClient() *Client

NewClient returns a Client with production-safe defaults derived from DefaultConfig.

func (*Client) Get

func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)

Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns the returned bytes.

func (*Client) Search

func (c *Client) Search(ctx context.Context, name string, count int, language string) ([]*Location, error)

Search queries the geocoding API for places matching name. count controls the maximum number of results; language is an ISO 639-1 code (e.g. "en").

type Config

type Config struct {
	BaseURL string
	Rate    time.Duration
	Retries int
	Timeout time.Duration
}

Config holds per-client tuning knobs. DefaultConfig returns ready-to-use values; a host may override individual fields.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns production-safe defaults.

type Domain

type Domain struct{}

Domain is the geocodingmeteo driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id) pair so `ant resolve` and `ant url` touch no network.

All-digits input is treated as a numeric location ID; everything else is a query string.

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Location

type Location struct {
	ID          int     `kit:"id" json:"id"`
	Name        string  `json:"name"`
	Latitude    float64 `json:"latitude"`
	Longitude   float64 `json:"longitude"`
	Elevation   float64 `json:"elevation"`
	Country     string  `json:"country"`
	CountryCode string  `json:"country_code"`
	Timezone    string  `json:"timezone"`
	Population  int     `json:"population"`
	Region      string  `json:"region"` // admin1
	FeatureCode string  `json:"feature_code"`
}

Location is one geocoding result: a city or named place returned by the Open-Meteo Geocoding API. The kit:"id" tag makes ID the resource address.