Merge pull request #2 from netloc8/feat/geo-accessors

feat: add RegionCode, Lat, Lng geo accessors

Author: tomvoss

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] — 2026-06-13
+
+### Added
+
+- `RegionCode()` accessor — returns the ISO 3166-2 subdivision code (e.g. `"CA"`), nil-safe
+- `Lat()` accessor — returns latitude coordinate, nil-safe
+- `Lng()` accessor — returns longitude coordinate, nil-safe
+- `HasCoordinates()` predicate — distinguishes absent coordinates from a real `0,0` location
+
+### Changed
+
+- README "Response Shape" section now uses `RegionCode()`, `Lat()`, `Lng()` accessors instead of raw field access
+
+### Fixed
+
+- README nil-safety note now correctly states accessors return zero values (empty strings or `0`), not just "empty strings"
+
 ## [1.1.0] — 2026-06-13
 
 ### Added

README.md

@@ -16,7 +16,7 @@ timezone-accurate scheduling, and regional content delivery.
 - **Zero dependencies** — only the Go standard library. No transitive dependency tree to audit
 - **Proxy-aware** — plug in any `*http.Client` with a proxy transport to discover exit IPs through tunnels
 - **Context-native** — every API call takes `context.Context` for cancellation, timeouts, and tracing
-- **Nil-safe accessors** — `geo.CountryCode()`, `geo.CityName()`, `geo.TZ()` never panic on partial responses
+- **Nil-safe accessors** — `geo.CountryCode()`, `geo.CityName()`, `geo.Lat()`, `geo.TZ()` never panic on partial responses
 - **Typed errors** — `*APIError` with machine-readable codes, `errors.As` support, and convenience predicates
 - **Privacy compliance ready** — `IsEU()` helper for GDPR, country and region fields for CCPA and other regulations
 
@@ -77,12 +77,12 @@ geo.CountryCode()                       // "US"
 geo.CountryName()                       // "United States"
 geo.Location.Country.Flag               // "🇺🇸"
 geo.Location.Country.Unions             // ["EU"] or []
-geo.Location.Region.Code                // "CA"
+geo.RegionCode()                        // "CA"
 geo.RegionName()                        // "California"
 geo.CityName()                          // "Mountain View"
 geo.Location.PostalCode                 // "94043"
-geo.Location.Coordinates.Latitude       // 37.386
-geo.Location.Coordinates.Longitude      // -122.084
+geo.Lat()                               // 37.386
+geo.Lng()                               // -122.084
 geo.TZ()                                // "America/Los_Angeles"
 geo.Location.UTCOffset                  // "-07:00"
 geo.Location.GeoConfidence              // 1.0
@@ -92,9 +92,10 @@ geo.Network.Domain                      // "google.com"
 geo.Meta.Precision                      // "city"
 ```
 
-All accessor methods (`CountryCode()`, `CityName()`, `TZ()`, etc.) are nil-safe
-— they return empty strings on nil or partial responses, so you never need to
-nil-check nested structs.
+All accessor methods (`CountryCode()`, `CityName()`, `Lat()`, `TZ()`, etc.) are nil-safe
+— they return zero values (empty strings or `0`) on nil or partial responses, so you
+never need to nil-check nested structs. Use `HasCoordinates()` to distinguish
+absent coordinates from a real `0,0` location.
 
 ## API Methods
 

geo.go

@@ -149,6 +149,15 @@ func ( g *Geo ) RegionName() string {
 	return g.Location.Region.Name
 }
 
+// RegionCode returns the ISO 3166-2 subdivision code (e.g. "CA"), or empty string.
+// Safe to call on nil Geo.
+func ( g *Geo ) RegionCode() string {
+	if g == nil || g.Location == nil || g.Location.Region == nil {
+		return ""
+	}
+	return g.Location.Region.Code
+}
+
 // CityName returns the city name, or empty string.
 // Safe to call on nil Geo.
 func ( g *Geo ) CityName() string {
@@ -158,6 +167,32 @@ func ( g *Geo ) CityName() string {
 	return g.Location.City
 }
 
+// Lat returns the latitude coordinate, or 0.
+// Safe to call on nil Geo.
+func ( g *Geo ) Lat() float64 {
+	if g == nil || g.Location == nil || g.Location.Coordinates == nil {
+		return 0
+	}
+	return g.Location.Coordinates.Latitude
+}
+
+// Lng returns the longitude coordinate, or 0.
+// Safe to call on nil Geo.
+func ( g *Geo ) Lng() float64 {
+	if g == nil || g.Location == nil || g.Location.Coordinates == nil {
+		return 0
+	}
+	return g.Location.Coordinates.Longitude
+}
+
+// HasCoordinates reports whether the geolocation result includes
+// coordinate data. Use this to distinguish absent coordinates from
+// a real 0,0 location (equator/prime meridian).
+// Safe to call on nil Geo.
+func ( g *Geo ) HasCoordinates() bool {
+	return g != nil && g.Location != nil && g.Location.Coordinates != nil
+}
+
 // TZ returns the IANA timezone string, or empty string.
 // Safe to call on nil Geo.
 func ( g *Geo ) TZ() string {

geo_test.go

@@ -83,6 +83,18 @@ func TestGeo_JSONRoundtrip( t *testing.T ) {
 	if decoded.CountryName() != "United States" {
 		t.Errorf( "CountryName() = %q, want United States", decoded.CountryName() )
 	}
+	if decoded.RegionCode() != "CA" {
+		t.Errorf( "RegionCode() = %q, want CA", decoded.RegionCode() )
+	}
+	if decoded.Lat() != 37.386 {
+		t.Errorf( "Lat() = %f, want 37.386", decoded.Lat() )
+	}
+	if decoded.Lng() != -122.084 {
+		t.Errorf( "Lng() = %f, want -122.084", decoded.Lng() )
+	}
+	if !decoded.HasCoordinates() {
+		t.Error( "HasCoordinates() should be true for full geo" )
+	}
 }
 
 func TestGeo_NilSafety( t *testing.T ) {
@@ -112,6 +124,18 @@ func TestGeo_NilSafety( t *testing.T ) {
 	if g.Org() != "" {
 		t.Error( "nil Geo.Org() should be empty" )
 	}
+	if g.RegionCode() != "" {
+		t.Error( "nil Geo.RegionCode() should be empty" )
+	}
+	if g.Lat() != 0 {
+		t.Error( "nil Geo.Lat() should be 0" )
+	}
+	if g.Lng() != 0 {
+		t.Error( "nil Geo.Lng() should be 0" )
+	}
+	if g.HasCoordinates() {
+		t.Error( "nil Geo.HasCoordinates() should be false" )
+	}
 
 	// Partial Geo with nil sub-structs.
 	partial := &Geo{}
@@ -121,6 +145,18 @@ func TestGeo_NilSafety( t *testing.T ) {
 	if partial.CityName() != "" {
 		t.Error( "empty Geo.CityName() should be empty" )
 	}
+	if partial.RegionCode() != "" {
+		t.Error( "empty Geo.RegionCode() should be empty" )
+	}
+	if partial.Lat() != 0 {
+		t.Error( "empty Geo.Lat() should be 0" )
+	}
+	if partial.Lng() != 0 {
+		t.Error( "empty Geo.Lng() should be 0" )
+	}
+	if partial.HasCoordinates() {
+		t.Error( "empty Geo.HasCoordinates() should be false" )
+	}
 }
 
 func TestGeo_ParseAPIResponse( t *testing.T ) {
@@ -276,20 +312,20 @@ func TestGeoFromPlatformHeaders( t *testing.T ) {
 		if geo.CountryCode() != "US" {
 			t.Errorf( "CountryCode() = %q, want US", geo.CountryCode() )
 		}
-		if geo.Location.Region.Code != "CA" {
-			t.Errorf( "Region.Code = %q, want CA", geo.Location.Region.Code )
+		if geo.RegionCode() != "CA" {
+			t.Errorf( "RegionCode() = %q, want CA", geo.RegionCode() )
 		}
 		if geo.CityName() != "Mountain View" {
 			t.Errorf( "CityName() = %q, want Mountain View", geo.CityName() )
 		}
 		if geo.TZ() != "America/Los_Angeles" {
 			t.Errorf( "TZ() = %q, want America/Los_Angeles", geo.TZ() )
 		}
-		if geo.Location.Coordinates.Latitude != 37.386 {
-			t.Errorf( "Latitude = %f, want 37.386", geo.Location.Coordinates.Latitude )
+		if geo.Lat() != 37.386 {
+			t.Errorf( "Lat() = %f, want 37.386", geo.Lat() )
 		}
-		if geo.Location.Coordinates.Longitude != -122.084 {
-			t.Errorf( "Longitude = %f, want -122.084", geo.Location.Coordinates.Longitude )
+		if geo.Lng() != -122.084 {
+			t.Errorf( "Lng() = %f, want -122.084", geo.Lng() )
 		}
 	})
 

version.go

@@ -2,4 +2,4 @@ package netloc8
 
 // Version is the semantic version of this SDK.
 // Updated at release time.
-const Version = "1.1.0"
+const Version = "1.2.0"