Geographic API: v1 Lookups & Canonical Governance Topology

EarthCoop now exposes a small versioned geography contract under /api/v1 for the first-party/native client. The application also retains older unversioned geography helpers and a richer canonical Location/Governance model. These layers must not be confused.

Current v1 geography endpoints

The current v1 route set includes native/client lookups for:

/api/v1/geography/countries
/api/v1/geography/provinces
/api/v1/geography/cities

Use the current route/controller tests for exact request parameters and response fields.

These endpoints are a versioned client contract for the data they expose. They are not a complete representation of every canonical governance level supported by EarthCoop.

Canonical topology is richer than the v1 lookup set

EarthCoop's current location/governance architecture is topology-aware. Supported structures can include:

cities with or without urban regions;
regions with or without neighborhoods;
villages with or without neighborhoods;
rural branches;
optional Street, Alley, Complex, Block/Building-style local detail where applicable;
pending proposed locations that participate in registration/governance flows under their own review/support rules.

Therefore:

v1 countries/provinces/cities lookup ≠ complete governance topology

A client that needs Primary Residence or governance membership semantics must follow the canonical product contract, not infer those semantics from a three-endpoint lookup family.

Legacy/unversioned geography routes

Older /api geography helpers still exist for web/compatibility flows. Their identifiers, hierarchy assumptions, and response shapes should not be treated as if they were automatically part of /api/v1.

Do not combine legacy helper behavior and v1 behavior into one invented stable schema. Bind to the exact versioned endpoint you use and keep the canonical governance model as the conceptual authority for residence/governance logic.

Authentication and exposure

The exact authentication requirement belongs to each current endpoint. The fact that a geography lookup can be exposed without member-specific state does not imply that all future governance/location operations should be public or unauthenticated.

Guidance for developers

For the native client, use the explicit /api/v1/geography/* routes currently provided. For richer Location/Governance workflows, use the corresponding canonical services/product contract. For third-party integration, do not assume the first-party v1 geography subset is an unrestricted public data API unless EarthCoop explicitly designates it as such.