Add Country deep geography types and drop Continent population_period.

Author: billyoshall

README.md

@@ -123,7 +123,7 @@ let place = parse.postal("28202", PostalOptions::default().country("US").deep(tr
 let property_tax = place.deep.as_ref().and_then(|deep| deep.property_tax.as_ref());
 ```
 
-Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population and its period remain in core.
+Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core.
 
 Point returns the timezone ID with the core location. Its optional deep detail adds terrain and compact nearest-city context on every plan. A nearest city is null when none is within 200 km.
 

src/types.rs

@@ -49,8 +49,6 @@ pub struct Continent {
 	pub region: String,
 	pub subregion: String,
 	pub population: Option<i64>,
-	/// Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable.
-	pub population_period: Option<String>,
 	pub area: Option<f64>,
 	pub emoji: String,
 }
@@ -1448,6 +1446,16 @@ pub struct CountryDeep {
 	/// Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable.
 	pub population_period: Option<String>,
 	pub area: Option<f64>,
+	/// Land area in km2.
+	pub land_area: Option<f64>,
+	/// Water area in km2.
+	pub water_area: Option<f64>,
+	/// Coastline length in km. Zero is a known landlocked coastline.
+	pub coastline: Option<f64>,
+	/// Mean elevation in metres above sea level.
+	pub elevation: Option<f64>,
+	pub lowest_point: Option<CountryElevationPoint>,
+	pub highest_point: Option<CountryElevationPoint>,
 	pub tld: Option<String>,
 	pub borders: Option<Vec<String>>,
 	pub blocs: Option<Vec<String>>,
@@ -1473,6 +1481,14 @@ pub struct CountryDeep {
 	pub plate: Option<String>,
 }
 
+#[derive(Debug, Clone, Deserialize)]
+#[non_exhaustive]
+pub struct CountryElevationPoint {
+	pub name: Option<String>,
+	/// Elevation in metres above sea level. Values below sea level are negative.
+	pub elevation: f64,
+}
+
 
 #[derive(Debug, Clone, Default, Deserialize)]
 #[serde(default)]

tests/country_geography.rs

@@ -0,0 +1,29 @@
+use parseapi::Country;
+
+#[test]
+fn country_geography_preserves_decimals_zero_and_negative_elevations() {
+	let country: Country = serde_json::from_str(r#"{"country":"XX","deep":{"land_area":10010.5,"water_area":0,"coastline":0,"elevation":0,"lowest_point":{"name":null,"elevation":-430.5},"highest_point":{"name":"Summit","elevation":8848.86}}}"#).unwrap();
+	let c = country.deep.unwrap();
+	assert_eq!(c.land_area, Some(10010.5));
+	assert_eq!(c.water_area, Some(0.0));
+	assert_eq!(c.coastline, Some(0.0));
+	assert_eq!(c.elevation, Some(0.0));
+	let low = c.lowest_point.unwrap();
+	assert_eq!(low.name, None);
+	assert_eq!(low.elevation, -430.5);
+	let high = c.highest_point.unwrap();
+	assert_eq!(high.name.as_deref(), Some("Summit"));
+	assert_eq!(high.elevation, 8848.86);
+}
+
+#[test]
+fn older_locked_and_null_country_geography_remain_unknown() {
+	for body in ["{}", r#"{"deep":{}}"#, r#"{"deep":{"land_area":null,"water_area":null,"coastline":null,"elevation":null,"lowest_point":null,"highest_point":null}}"#] {
+		let country: Country = serde_json::from_str(body).unwrap();
+		assert_eq!(country.deep.is_none(), body == "{}");
+		if let Some(c) = country.deep {
+			assert!(c.land_area.is_none() && c.water_area.is_none() && c.coastline.is_none() && c.elevation.is_none());
+			assert!(c.lowest_point.is_none() && c.highest_point.is_none());
+		}
+	}
+}