maidenhead

README

Station Manager: maidenhead package

This module provides a simple API for Maidenhead locator (grid square) calculations.

It can be used standalone (via its own go.mod) or as part of the wider Station Manager system.

Features

• Convert Maidenhead grid squares (6-character locators like JN58td) to latitude/longitude.
• Compute great-circle (short-path) distance and initial bearing between two grid squares.
• Compute long-path distance and bearing (the complementary path around the globe).
• Provide a convenient Location struct bundling all of the above.

Inputs are case-insensitive: JN58TD and jn58td are treated identically.

Installation

If you want to use this package directly in another Go project:

go get github.com/Station-Manager/maidenhead

Then import it in your code:

import "github.com/Station-Manager/maidenhead"

Basic usage

Get a full location summary

loc, err := maidenhead.GetLocation("JN58td", "FN31pr")
if err != nil {
    // handle error (invalid grid, etc.)
}

fmt.Printf("Short-path: bearing=%.1f°, distance=%d km (%d mi)\n",
    loc.ShortPathBearing,
    loc.ShortPathDistanceKm,
    loc.ShortPathDistanceMiles,
)
fmt.Printf("Long-path:  bearing=%.1f°, distance=%d km (%d mi)\n",
    loc.LongPathBearing,
    loc.LongPathDistanceKm,
    loc.LongPathDistanceMiles,
)

Convert a grid square to latitude/longitude

lat, err := maidenhead.LatitudeFromGridSquare("JN58td")
if err != nil {
    // handle invalid locator
}

lon, err := maidenhead.LongitudeFromGridSquare("JN58td")
if err != nil {
    // handle invalid locator
}

fmt.Printf("JN58td center: lat=%.5f lon=%.5f\n", lat, lon)

Compute short-path distance and bearing only

bearing, err := maidenhead.GetShortPathBearing("JN58td", "FN31pr")
if err != nil {
    // handle invalid input
}

km, miles, err := maidenhead.GetShortPathDistance("JN58td", "FN31pr")
if err != nil {
    // handle invalid input
}

fmt.Printf("Short path: bearing=%.1f°, distance=%.0f km (%.0f mi)\n", bearing, km, miles)

Compute long-path distance and bearing

lpBearing, err := maidenhead.GetLongPathBearing("JN58td", "FN31pr")
if err != nil {
    // handle invalid input
}

lpKm, lpMiles, err := maidenhead.GetLongPathDistance("JN58td", "FN31pr")
if err != nil {
    // handle invalid input
}

fmt.Printf("Long path: bearing=%.1f°, distance=%.0f km (%.0f mi)\n", lpBearing, lpKm, lpMiles)

API overview

Types

type Location struct

type Location struct {
    LocalGridSquare        string  `json:"localGridSquare"`
    RemoteGridSquare       string  `json:"remoteGridSquare"`
    ShortPathBearing       float64 `json:"short_path_bearing"`
    LongPathBearing        float64 `json:"long_path_bearing"`
    ShortPathDistanceKm    int64   `json:"short_path_distance_km"`
    ShortPathDistanceMiles int64   `json:"short_path_distance_miles"`
    LongPathDistanceKm     int64   `json:"long_path_distance_km"`
    LongPathDistanceMiles  int64   `json:"long_path_distance_miles"`
}

Exported functions

All functions live in the maidenhead package.

• GetLocation(localGrid, remoteGrid string) (*Location, error)
  High-level helper: validates the given 6-character grid squares, computes short- and long-path bearings and distances, and returns them in a Location struct.

• GetShortPathBearing(localGrid, remoteGrid string) (float64, error)
  Returns the initial great-circle bearing (0–360°, rounded to 0.1°) from localGrid to remoteGrid.

• GetLongPathBearing(localGrid, remoteGrid string) (float64, error)
  Returns the bearing for the complementary “long path” (opposite side of the globe), also in degrees.

• GetShortPathDistance(localGrid, remoteGrid string) (km, miles float64, err error)
  Returns the great-circle distance between two locators in kilometers and miles, both rounded up using math.Ceil.

• GetLongPathDistance(localGrid, remoteGrid string) (km, miles float64, err error)
  Returns the long-path distance (Earth circumference minus short-path distance), in kilometers and miles.

• LatitudeFromGridSquare(grid string) (float64, error)
  Converts a 6-character Maidenhead locator to latitude (center of the subsquare). Input is case-insensitive.

• LongitudeFromGridSquare(grid string) (float64, error)
  Converts a 6-character Maidenhead locator to longitude (center of the subsquare). Input is case-insensitive.

• CalculateBearing(lat1, lon1, lat2, lon2 float64) float64
  Low-level helper that returns the initial great-circle bearing between two latitude/longitude points in degrees.

Validation rules

The current implementation expects 6-character Maidenhead grid squares in the form AA99aa:

• 1st and 2nd characters: letters A–R (fields), case-insensitive.
• 3rd and 4th characters: digits 0–9 (squares).
• 5th and 6th characters: letters a–x (subsquares), case-insensitive on input.

Invalid strings (wrong length or characters out of range) will result in an error from the conversion/lookup functions.

Testing and coverage

From the repository root you can run:

cd maidenhead

go test ./...

From the Station Manager root (where go.work lives), you can run tests and coverage for just this module:

cd /home/mveary/Development/Station-Manager

go test ./maidenhead -coverprofile=maidenhead.cover.out -covermode=count

go tool cover -func=maidenhead.cover.out | grep maidenhead

This module currently has tests covering bearing math, grid validation and normalization, coordinate conversion, and short/long path distance and bearing calculations.

Notes and limitations

• The Earth is modeled as a sphere with radius 6371 km (standard great-circle assumptions); results are approximate but suitable for radio/contest logging and routing use-cases.
• Distances are rounded up to the nearest kilometer/mile using math.Ceil.
• Bearings are normalized into the range [0, 360) and rounded to one decimal place.
• Only 6-character grid squares are supported by this package at present.

Documentation

Index

• func CalculateBearing(lat1, lon1, lat2, lon2 float64) float64
• func GetLongPathBearing(localGridSquare, remoteGridSquare string) (float64, error)
• func GetLongPathDistance(localGridSquare, remoteGridSquare string) (float64, float64, error)
• func GetShortPathBearing(localGridSquare, remoteGridSquare string) (float64, error)
• func GetShortPathDistance(localGridSquare, remoteGridSquare string) (float64, float64, error)
• func LatitudeFromGridSquare(gridSquare string) (float64, error)
• func LongitudeFromGridSquare(gridSquare string) (float64, error)
• type Location
  • func GetLocation(localGridSquare, remoteGridSquare string) (*Location, error)

Functions

func CalculateBearing

func CalculateBearing(lat1, lon1, lat2, lon2 float64) float64

CalculateBearing calculates the initial bearing (or heading) from one point to another given their latitude and longitude coordinates.

Parameters:

• lat1: Latitude of the starting point in degrees
• lon1: Longitude of the starting point in degrees
• lat2: Latitude of the destination point in degrees
• lon2: Longitude of the destination point in degrees

Returns:

• float64: The initial bearing in degrees from the starting point to the destination (0-360°), rounded to the nearest 0.1 degree

func GetLongPathBearing

func GetLongPathBearing(localGridSquare, remoteGridSquare string) (float64, error)

func GetLongPathDistance

func GetLongPathDistance(localGridSquare, remoteGridSquare string) (float64, float64, error)

func GetShortPathBearing

func GetShortPathBearing(localGridSquare, remoteGridSquare string) (float64, error)

GetShortPathBearing computes the initial bearing between two Maidenhead Grid Square locations. It takes two grid square strings (case-insensitive), validates them, and returns the bearing in degrees or an error if invalid.

Parameters:

• localGridSquare: The Maidenhead Grid Square of the local station (6 characters)
• remoteGridSquare: The Maidenhead Grid Square of the remote station (6 characters)

Returns:

• float64: The bearing in degrees from the local to the remote grid square (0-360°)
• error: An error if either grid square is invalid

func GetShortPathDistance

func GetShortPathDistance(localGridSquare, remoteGridSquare string) (float64, float64, error)

GetShortPathDistance calculates the distance in kilometers and miles between two Maidenhead Grid Square locations. It takes two grid square strings (case-insensitive) as input and returns the distances and an error if the inputs are invalid.

Parameters:

• localGridSquare: The Maidenhead Grid Square of the local station (6 characters)
• remoteGridSquare: The Maidenhead Grid Square of the remote station (6 characters)

Returns:

• float64: The distance in kilometers between the grid squares
• float64: The distance in miles between the grid squares
• error: An error if either grid square is invalid

func LatitudeFromGridSquare

func LatitudeFromGridSquare(gridSquare string) (float64, error)

LatitudeFromGridSquare calculates the latitude from a Maidenhead Grid Square identifier. The input gridSquare is case-insensitive and must be a valid 6-character grid square format. Returns the latitude or an error if the input is invalid.

func LongitudeFromGridSquare

func LongitudeFromGridSquare(gridSquare string) (float64, error)

LongitudeFromGridSquare calculates the longitude from a Maidenhead Grid Square and returns it as a float64. It expects a 6-character grid square string (case-insensitive) and validates its format before processing.

Types

type Location

type Location struct {
	LocalGridSquare        string  `json:"localGridSquare"`
	RemoteGridSquare       string  `json:"remoteGridSquare"`
	ShortPathBearing       float64 `json:"short_path_bearing"`
	LongPathBearing        float64 `json:"long_path_bearing"`
	ShortPathDistanceKm    int64   `json:"short_path_distance_km"`
	ShortPathDistanceMiles int64   `json:"short_path_distance_miles"`
	LongPathDistanceKm     int64   `json:"long_path_distance_km"`
	LongPathDistanceMiles  int64   `json:"long_path_distance_miles"`
}

func GetLocation

func GetLocation(localGridSquare, remoteGridSquare string) (*Location, error)

GetLocation calculates the distance, bearing, and other information between two Maidenhead Grid Square locations. It returns a `Location` struct containing the computed results or an error if the inputs are invalid. Grid square input is case-insensitive (e.g., JN58TD and jn58td are both accepted).

Parameters:

• localGridSquare: The Maidenhead Grid Square of the local station (6 characters)
• remoteGridSquare: The Maidenhead Grid Square of the remote station (6 characters)

Returns:

• *Location: A struct containing the bearing, distance in km and miles, and the original grid squares
• error: An error if either grid square is invalid or if calculations fail