domain tier

domain-geo

Geographic types for locations, coordinates, addresses, and service areas

Geographic types for locations, coordinates, addresses, and service areas

Tierdomain
Roleunclassified (baselined)
Pathcrates/domain/geo
Edition2021
Targetsdomain_geo
Public items93 across 3 modules
Tests55

What it is for

# domain-geo

Geographic types for locations, coordinates, addresses, and service areas.

Core Features

Example

use domain_geo::{Coordinate, units};

// Create coordinates
let nyc = Coordinate::new(40.7128, -74.0060).unwrap();
let la = Coordinate::new(34.0522, -118.2437).unwrap();

// Calculate distance
let distance_m = nyc.distance_to(&la);
let distance_km = units::meters_to_kilometers(distance_m);
assert!(distance_km > 3900.0 && distance_km < 4000.0);

Capabilities

crate root

# domain-geo

Item
pub const EARTH_RADIUS_METERS: f64

Address

# domain-geo

Item
pub struct Address
Address :: fn builder() -> AddressBuilder
Address :: fn format_single_line(& self) -> String
Address :: fn format_multiline(& self) -> String

AddressBuilder

# domain-geo

Item
pub struct AddressBuilder
AddressBuilder :: fn new() -> Self
AddressBuilder :: fn street1(mut self, street1 : impl Into <String>) -> Self
AddressBuilder :: fn street2(mut self, street2 : impl Into <String>) -> Self
AddressBuilder :: fn city(mut self, city : impl Into <String>) -> Self
AddressBuilder :: fn state(mut self, state : impl Into <String>) -> Self
AddressBuilder :: fn postal_code(mut self, postal_code : impl Into <String>) -> Self
AddressBuilder :: fn country(mut self, country : impl Into <String>) -> Self
AddressBuilder :: fn build(self) -> Result <Address, GeoError>

BoundingBox

# domain-geo

Item
pub struct BoundingBox
BoundingBox :: fn new(min : Coordinate, max : Coordinate) -> Self
BoundingBox :: fn from_coordinates(coords : & Coordinate) -> Option <Self>
BoundingBox :: fn contains(& self, point : & Coordinate) -> bool
BoundingBox :: fn intersects(& self, other : & BoundingBox) -> bool
BoundingBox :: fn expand(& self, point : & Coordinate) -> Self
BoundingBox :: fn center(& self) -> Coordinate
BoundingBox :: fn width(& self) -> f64
BoundingBox :: fn height(& self) -> f64

Coordinate

# domain-geo

Item
pub struct Coordinate
Coordinate :: fn new(latitude : f64, longitude : f64) -> Result <Self, GeoError>
Coordinate :: fn latitude(& self) -> f64
Coordinate :: fn longitude(& self) -> f64
Coordinate :: fn distance_to(& self, other : & Self) -> f64
Coordinate :: fn bearing_to(& self, other : & Self) -> f64
Coordinate :: fn midpoint(& self, other : & Self) -> Self
Coordinate :: fn destination(& self, bearing : f64, distance : f64) -> Self
Coordinate :: fn is_within(& self, other : & Self, distance_meters : f64) -> bool

Direction

# domain-geo

Item
pub enum Direction
Direction :: fn from_bearing(bearing : f64) -> Self
Direction :: fn bearing(& self) -> f64
Direction :: fn abbreviation(& self) -> & 'static str

GeoError

# domain-geo

Item
pub enum GeoError

Place

# domain-geo

Item
pub struct Place
Place :: fn builder() -> PlaceBuilder
Place :: fn has_coordinates(& self) -> bool
Place :: fn has_address(& self) -> bool
Place :: fn distance_to(& self, other : & Place) -> Option <f64>
Place :: fn id(& self) -> Uuid
Place :: fn created_at(& self) -> DateTime <Utc>
Place :: fn updated_at(& self) -> DateTime <Utc>
Place :: fn deleted_at(& self) -> Option <DateTime <Utc>>

PlaceBuilder

# domain-geo

Item
pub struct PlaceBuilder
PlaceBuilder :: fn new() -> Self
PlaceBuilder :: fn name(mut self, name : impl Into <String>) -> Self
PlaceBuilder :: fn coordinate(mut self, coordinate : Coordinate) -> Self
PlaceBuilder :: fn address(mut self, address : Address) -> Self
PlaceBuilder :: fn place_type(mut self, place_type : PlaceType) -> Self
PlaceBuilder :: fn timezone(mut self, timezone : impl Into <String>) -> Self
PlaceBuilder :: fn build(self) -> Result <Place, GeoError>

PlaceType

# domain-geo

Item
pub enum PlaceType

ServiceArea

# domain-geo

Item
pub struct ServiceArea
ServiceArea :: fn builder() -> ServiceAreaBuilder
ServiceArea :: fn contains(& self, point : & Coordinate) -> bool
ServiceArea :: fn bounding_box(& self) -> Option <BoundingBox>
ServiceArea :: fn centroid(& self) -> Option <Coordinate>
ServiceArea :: fn area_estimate(& self) -> f64
ServiceArea :: fn vertex_count(& self) -> usize
ServiceArea :: fn id(& self) -> Uuid
ServiceArea :: fn created_at(& self) -> DateTime <Utc>
ServiceArea :: fn updated_at(& self) -> DateTime <Utc>
ServiceArea :: fn deleted_at(& self) -> Option <DateTime <Utc>>

ServiceAreaBuilder

# domain-geo

Item
pub struct ServiceAreaBuilder
ServiceAreaBuilder :: fn new() -> Self
ServiceAreaBuilder :: fn name(mut self, name : impl Into <String>) -> Self
ServiceAreaBuilder :: fn add_vertex(mut self, coord : Coordinate) -> Self
ServiceAreaBuilder :: fn boundary(mut self, boundary : Vec <Coordinate>) -> Self
ServiceAreaBuilder :: fn description(mut self, description : impl Into <String>) -> Self
ServiceAreaBuilder :: fn is_active(mut self, is_active : bool) -> Self
ServiceAreaBuilder :: fn build(self) -> Result <ServiceArea, GeoError>

address (other)

Structs + a transaction-scoped repo over geo_addresses/geo_places

Item
async fn insert_address_tx(tx : & mut Transaction <'_, Postgres>, street1 : & str, street2 : Option <& str>, city : & str, state : Option <& str>, postal_code : Option <& str>, country : & str,) -> Result <GeoAddress, GeoRepoError>
async fn update_address_tx(tx : & mut Transaction <'_, Postgres>, id : Uuid, street1 : & str, street2 : Option <& str>, city : & str, state : Option <& str>, postal_code : Option <& str>, country : & str,) -> Result <Option <GeoAddress>, GeoRepoError>
async fn insert_place_tx(tx : & mut Transaction <'_, Postgres>, name : & str, address_id : Uuid,) -> Result <GeoPlace, GeoRepoError>

GeoAddress

Structs + a transaction-scoped repo over geo_addresses/geo_places

Item
pub struct GeoAddress

GeoPlace

Structs + a transaction-scoped repo over geo_addresses/geo_places

Item
pub struct GeoPlace

GeoRepoError

Structs + a transaction-scoped repo over geo_addresses/geo_places

Item
pub enum GeoRepoError

GeoIpError

Geo-IP resolution — turning an IP address into an approximate

Item
pub enum GeoIpError

GeoIpRecord

Geo-IP resolution — turning an IP address into an approximate

Item
pub struct GeoIpRecord
GeoIpRecord :: fn is_empty(& self) -> bool

GeoIpResolver

Geo-IP resolution — turning an IP address into an approximate

Item
pub trait GeoIpResolver

MaxMindGeoIpResolver

Geo-IP resolution — turning an IP address into an approximate

Item
pub struct MaxMindGeoIpResolver
MaxMindGeoIpResolver :: fn open <P : AsRef <Path>>(path : P) -> Result <Self, GeoIpError>
MaxMindGeoIpResolver :: fn lookup(& self, ip : IpAddr) -> Option <GeoIpRecord>

units (other)

_No module-level documentation is present in the source._

Item
fn meters_to_kilometers(m : f64) -> f64
fn meters_to_miles(m : f64) -> f64
fn meters_to_feet(m : f64) -> f64
fn kilometers_to_meters(km : f64) -> f64
fn miles_to_meters(mi : f64) -> f64
fn feet_to_meters(ft : f64) -> f64

How to use it

From this crate's own rustdoc:

use domain_geo::{Coordinate, units};

// Create coordinates
let nyc = Coordinate::new(40.7128, -74.0060).unwrap();
let la = Coordinate::new(34.0522, -118.2437).unwrap();

// Calculate distance
let distance_m = nyc.distance_to(&la);
let distance_km = units::meters_to_kilometers(distance_m);
assert!(distance_km > 3900.0 && distance_km < 4000.0);

Module structure

domain_geo

flowchart TD
  n_domain_geo["domain_geo"]
  n_domain_geo --> n_address["address"]
  n_domain_geo --> n_geoip["geoip"]
  n_domain_geo --> n_units["units"]

Public surface

`crate root`

ItemWhat it is
pub const EARTH_RADIUS_METERS: f64Earth's mean radius in meters (WGS84).
pub enum GeoErrorGeographic errors.
pub struct CoordinateA geographic coordinate (latitude/longitude pair)
Coordinate :: fn new(latitude : f64, longitude : f64) -> Result <Self, GeoError>Create a new coordinate with validation
Coordinate :: fn latitude(& self) -> f64Get the latitude.
Coordinate :: fn longitude(& self) -> f64Get the longitude.
Coordinate :: fn distance_to(& self, other : & Self) -> f64Calculate the distance to another coordinate in meters
Coordinate :: fn bearing_to(& self, other : & Self) -> f64Calculate the initial bearing to another coordinate in degrees
Coordinate :: fn midpoint(& self, other : & Self) -> SelfCalculate the midpoint between this coordinate and another.
Coordinate :: fn destination(& self, bearing : f64, distance : f64) -> SelfCalculate a destination point given bearing and distance
Coordinate :: fn is_within(& self, other : & Self, distance_meters : f64) -> boolCheck if this coordinate is within a given distance of another.
pub struct BoundingBoxA rectangular geographic area defined by min/max coordinates.
BoundingBox :: fn new(min : Coordinate, max : Coordinate) -> SelfCreate a new bounding box.
BoundingBox :: fn from_coordinates(coords : & Coordinate) -> Option <Self>Create a bounding box from a set of coordinates
BoundingBox :: fn contains(& self, point : & Coordinate) -> boolCheck if a point is within the bounding box.
BoundingBox :: fn intersects(& self, other : & BoundingBox) -> boolCheck if this bounding box intersects another.
BoundingBox :: fn expand(& self, point : & Coordinate) -> SelfExpand the bounding box to include a point.
BoundingBox :: fn center(& self) -> CoordinateGet the center of the bounding box.
BoundingBox :: fn width(& self) -> f64Get the width in degrees longitude.
BoundingBox :: fn height(& self) -> f64Get the height in degrees latitude.
pub struct AddressA structured postal address.
Address :: fn builder() -> AddressBuilderCreate a new address builder.
Address :: fn format_single_line(& self) -> StringFormat the address as a single line.
Address :: fn format_multiline(& self) -> StringFormat the address as multiple lines.
pub struct AddressBuilderBuilder for Address.
AddressBuilder :: fn new() -> SelfCreate a new builder.
AddressBuilder :: fn street1(mut self, street1 : impl Into <String>) -> SelfSet the primary street address.
AddressBuilder :: fn street2(mut self, street2 : impl Into <String>) -> SelfSet the secondary street address.
AddressBuilder :: fn city(mut self, city : impl Into <String>) -> SelfSet the city.
AddressBuilder :: fn state(mut self, state : impl Into <String>) -> SelfSet the state or province.
AddressBuilder :: fn postal_code(mut self, postal_code : impl Into <String>) -> SelfSet the postal code.
AddressBuilder :: fn country(mut self, country : impl Into <String>) -> SelfSet the country.
AddressBuilder :: fn build(self) -> Result <Address, GeoError>Build the address
pub enum PlaceTypeType of geographic place.
pub struct PlaceA named geographic location.
Place :: fn builder() -> PlaceBuilderCreate a new place builder.
Place :: fn has_coordinates(& self) -> boolCheck if this place has coordinates.
Place :: fn has_address(& self) -> boolCheck if this place has an address.
Place :: fn distance_to(& self, other : & Place) -> Option <f64>Calculate distance to another place in meters
Place :: fn id(& self) -> Uuid
Place :: fn created_at(& self) -> DateTime <Utc>
Place :: fn updated_at(& self) -> DateTime <Utc>
Place :: fn deleted_at(& self) -> Option <DateTime <Utc>>
pub struct PlaceBuilderBuilder for Place.
PlaceBuilder :: fn new() -> SelfCreate a new builder.
PlaceBuilder :: fn name(mut self, name : impl Into <String>) -> SelfSet the place name.
PlaceBuilder :: fn coordinate(mut self, coordinate : Coordinate) -> SelfSet the coordinate.
PlaceBuilder :: fn address(mut self, address : Address) -> SelfSet the address.
PlaceBuilder :: fn place_type(mut self, place_type : PlaceType) -> SelfSet the place type.
PlaceBuilder :: fn timezone(mut self, timezone : impl Into <String>) -> SelfSet the timezone.
PlaceBuilder :: fn build(self) -> Result <Place, GeoError>Build the place
pub struct ServiceAreaA polygonal geographic service area.
ServiceArea :: fn builder() -> ServiceAreaBuilderCreate a new service area builder.
ServiceArea :: fn contains(& self, point : & Coordinate) -> boolCheck if a point is within this service area
ServiceArea :: fn bounding_box(& self) -> Option <BoundingBox>Get the bounding box of this service area.
ServiceArea :: fn centroid(& self) -> Option <Coordinate>Calculate the centroid (center of mass) of the polygon.
ServiceArea :: fn area_estimate(& self) -> f64Estimate the area in square meters
ServiceArea :: fn vertex_count(& self) -> usizeGet the number of vertices in the boundary.
ServiceArea :: fn id(& self) -> Uuid
ServiceArea :: fn created_at(& self) -> DateTime <Utc>
ServiceArea :: fn updated_at(& self) -> DateTime <Utc>
ServiceArea :: fn deleted_at(& self) -> Option <DateTime <Utc>>
pub struct ServiceAreaBuilderBuilder for ServiceArea.
ServiceAreaBuilder :: fn new() -> SelfCreate a new builder.
ServiceAreaBuilder :: fn name(mut self, name : impl Into <String>) -> SelfSet the area name.
ServiceAreaBuilder :: fn add_vertex(mut self, coord : Coordinate) -> SelfAdd a vertex to the boundary.
ServiceAreaBuilder :: fn boundary(mut self, boundary : Vec <Coordinate>) -> SelfSet the boundary from a vector of coordinates.
ServiceAreaBuilder :: fn description(mut self, description : impl Into <String>) -> SelfSet the description.
ServiceAreaBuilder :: fn is_active(mut self, is_active : bool) -> SelfSet whether the area is active.
ServiceAreaBuilder :: fn build(self) -> Result <ServiceArea, GeoError>Build the service area
pub enum DirectionCardinal and intercardinal directions.
Direction :: fn from_bearing(bearing : f64) -> SelfGet the direction from a bearing in degrees.
Direction :: fn bearing(& self) -> f64Get the bearing for this direction.
Direction :: fn abbreviation(& self) -> & 'static strGet the abbreviation (N, NE, E, etc.).

`address`

ItemWhat it is
pub struct GeoAddressA structured postal address (geo_addresses), column-for-column.
pub struct GeoPlaceA named location (geo_places), optionally anchored to a GeoAddress via address_id.
pub enum GeoRepoErrorErrors from this module's queries
async fn insert_address_tx(tx : & mut Transaction <'_, Postgres>, street1 : & str, street2 : Option <& str>, city : & str, state : Option <& str>, postal_code : Option <& str>, country : & str,) -> Result <GeoAddress, GeoRepoError>Insert a geo_addresses row inside the caller's transaction
async fn update_address_tx(tx : & mut Transaction <'_, Postgres>, id : Uuid, street1 : & str, street2 : Option <& str>, city : & str, state : Option <& str>, postal_code : Option <& str>, country : & str,) -> Result <Option <GeoAddress>, GeoRepoError>Update a geo_addresses row in place, inside the caller's transaction
async fn insert_place_tx(tx : & mut Transaction <'_, Postgres>, name : & str, address_id : Uuid,) -> Result <GeoPlace, GeoRepoError>Insert a geo_places row anchored to address_id, inside the caller's transaction

`geoip`

ItemWhat it is
pub struct GeoIpRecordAn approximate location resolved from an IP address
GeoIpRecord :: fn is_empty(& self) -> boolWhether no field resolved — an empty record is as good as no match, and callers generally store NULL geo for it.
pub trait GeoIpResolverResolves IP addresses to approximate locations
pub enum GeoIpErrorFailure constructing a MaxMindGeoIpResolver.
pub struct MaxMindGeoIpResolverA GeoIpResolver backed by a local MaxMind GeoLite2 City .mmdb
MaxMindGeoIpResolver :: fn open <P : AsRef <Path>>(path : P) -> Result <Self, GeoIpError>Open a MaxMind .mmdb from a filesystem path
MaxMindGeoIpResolver :: fn lookup(& self, ip : IpAddr) -> Option <GeoIpRecord>

`units`

ItemWhat it is
fn meters_to_kilometers(m : f64) -> f64Convert meters to kilometers.
fn meters_to_miles(m : f64) -> f64Convert meters to miles.
fn meters_to_feet(m : f64) -> f64Convert meters to feet.
fn kilometers_to_meters(km : f64) -> f64Convert kilometers to meters.
fn miles_to_meters(mi : f64) -> f64Convert miles to meters.
fn feet_to_meters(ft : f64) -> f64Convert feet to meters.

Re-exports. Exported here, defined elsewhere.

ExportDefined in
{GeoIpError,GeoIpRecord,GeoIpResolver,MaxMindGeoIpResolver}geoip::{GeoIpError,GeoIpRecord,GeoIpResolver,MaxMindGeoIpResolver}

Boundary

Reaches into foundation.

Shares tier domain with 41 other crates: domain-agreements, domain-ai-report, domain-billing, domain-catalog, domain-classify, domain-comments, domain-competitive-intel, domain-contact, … (41 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)domain
Architectural role (taxonomy)unclassified (baselined)
Locationcrates/domain/geo
Vocabulary in force (lexicon)current

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_domain["domain"] --> n_foundation["foundation"]

Dependencies

Runtime, in this workspace.

CrateTierOptionalOnly on
`foundation-basemodels`foundationnoalways

Runtime, from outside the workspace.

CrateRequirementFeaturesOptionalOnly on
chrono^0.4serdenoalways
maxminddb^0.27yesalways
serde^1derivenoalways
serde_json^1noalways
sqlx^0.8runtime-tokio, postgres, chrono, uuidnoalways
thiserror^2noalways
uuid^1v4, serdenoalways

Development, from outside the workspace.

CrateRequirementFeaturesOptionalOnly on
tokio-test^0.4noalways

Build. None.

Depended on by. 3 workspace crates.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_application_geo["application-geo"] -->|uses| SELF
  n_identity_party_places["identity-party-places"] -->|uses| SELF
  n_platform_privacy_scan_api["platform-privacy-scan-api"] -->|uses| SELF
  SELF["domain-geo"]
  SELF -->|runtime| n_foundation_basemodels["foundation-basemodels"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

FeatureEnablesOn by default
defaultyes
geoipdep:maxminddbno
flowchart LR
  n_default["default"]
  n_geoip["geoip"] --> n_dep_maxminddb["dep:maxminddb"]

Targets

KindNameSource
libdomain_geo`src/lib.rs`

Error model

Error typeNamed by
GeoErrordeclared, no public signature returns it
GeoIpErrordeclared, no public signature returns it
GeoRepoErrorinsert_address_tx, insert_place_tx, update_address_tx

Operational characteristics

PropertyEvidence
async public surfaceyes
async runtimenone detected
database accessyes
network I/Onone detected
unsafe codenone detected
environment variablesnone detected

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

3 workspace crates depend on this one: application-geo, identity-party-places, platform-privacy-scan-api.

Verification

KindCount
Unit tests55
Integration tests0
Examples0
Doctests1

Evidence by module. How often each public module is named by something executable.

ModuleTestsExamplesConsumers
crate root1202
address604
geoip400
units601

What the tests establish, by name:

Documentation coverage

MeasureDocumentedTotal
Public items with rustdoc8493
Public modules with a //! block23
pie showData
    title Public items with rustdoc
    "Documented" : 84
    "No rustdoc detected" : 9

Metrics

MetricValue
Rust source files3
Source lines2015
Code lines1384
Public API items93
Public modules3
Tests55
Examples0
Cargo features2
Direct runtime dependencies8
Workspace reverse dependencies3
pie showData
    title Public API by kind
    "constant" : 1
    "enum" : 5
    "function" : 9
    "method" : 65
    "struct" : 12
    "trait" : 1
pie showData
    title Rust source composition
    "Code" : 1384
    "Blank or comment" : 631

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

All domain · Manual