Fix issue #147: Add helper methods to extract address components from Places Details API (#176)

maximn · web-flow · commit 9ea17f49813e · 2025-09-03T21:03:30.000+03:00
- Add GetStreetAddress(), GetState(), GetPostalCode(), GetCity(), GetCountry() methods to Result class - Add GetAddressBreakdown() method that returns a structured AddressBreakdown object - Add comprehensive integration tests demonstrating usage - Add example code showing how to extract address components - Extract hardcoded place IDs to constants for better maintainability - Remove unnecessary AddressComponentExtensions class in favor of direct class methods This addresses GitHub issue #147: 'How do i get the street address, state, and postal code from the place results?'
diff --git a/GoogleMapsApi.Test/IntegrationTests/PlacesDetailsAddressComponentTests.cs b/GoogleMapsApi.Test/IntegrationTests/PlacesDetailsAddressComponentTests.cs
@@ -0,0 +1,152 @@
+using System.Linq;
+using System.Threading.Tasks;
+using GoogleMapsApi.Entities.PlacesDetails.Request;
+using GoogleMapsApi.Entities.PlacesDetails.Response;
+using NUnit.Framework;
+using GoogleMapsApi.Test.Utils;
+
+namespace GoogleMapsApi.Test.IntegrationTests
+{
+    [TestFixture]
+    public class PlacesDetailsAddressComponentTests : BaseTestIntegration
+    {
+        private const string GoogleSydneyOfficePlaceId = "ChIJN1t_tDeuEmsRUsoyG83frY4";
+
+        [Test]
+        public async Task CanExtractStreetAddressFromPlacesDetails()
+        {
+            // Test with a known place that has a street address
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+            Assert.That(result.Result.AddressComponent, Is.Not.Null.And.Not.Empty);
+
+            // Extract street address using the helper method
+            var streetAddress = result.Result.GetStreetAddress();
+            Assert.That(streetAddress, Is.Not.Null.And.Not.Empty);
+            Assert.That(streetAddress, Does.Contain("Pirrama"));
+        }
+
+        [Test]
+        public async Task CanExtractStateFromPlacesDetails()
+        {
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+
+            // Extract state using the helper method
+            var state = result.Result.GetState();
+            var stateShort = result.Result.GetState(useShortName: true);
+            
+            Assert.That(state, Is.Not.Null.And.Not.Empty);
+            Assert.That(stateShort, Is.Not.Null.And.Not.Empty);
+        }
+
+        [Test]
+        public async Task CanExtractPostalCodeFromPlacesDetails()
+        {
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+
+            // Extract postal code using the helper method
+            var postalCode = result.Result.GetPostalCode();
+            Assert.That(postalCode, Is.Not.Null.And.Not.Empty);
+        }
+
+        [Test]
+        public async Task CanExtractCompleteAddressBreakdown()
+        {
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+
+            // Extract complete address breakdown
+            var addressBreakdown = result.Result.GetAddressBreakdown();
+            
+            Assert.That(addressBreakdown, Is.Not.Null);
+            Assert.That(addressBreakdown.StreetAddress, Is.Not.Null.And.Not.Empty);
+            Assert.That(addressBreakdown.City, Is.Not.Null.And.Not.Empty);
+            Assert.That(addressBreakdown.State, Is.Not.Null.And.Not.Empty);
+            Assert.That(addressBreakdown.PostalCode, Is.Not.Null.And.Not.Empty);
+            Assert.That(addressBreakdown.Country, Is.Not.Null.And.Not.Empty);
+
+            // Test the ToString method
+            var formattedAddress = addressBreakdown.ToString();
+            Assert.That(formattedAddress, Is.Not.Null.And.Not.Empty);
+            Assert.That(formattedAddress, Does.Contain(","));
+        }
+
+        [Test]
+        public async Task CanExtractCityFromPlacesDetails()
+        {
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+
+            // Extract city using the helper method
+            var city = result.Result.GetCity();
+            Assert.That(city, Is.Not.Null.And.Not.Empty);
+            // Google Sydney office is in Pyrmont, which is a suburb of Sydney
+            Assert.That(city, Is.EqualTo("Pyrmont"));
+        }
+
+        [Test]
+        public async Task CanExtractCountryFromPlacesDetails()
+        {
+            var request = new PlacesDetailsRequest
+            {
+                ApiKey = ApiKey,
+                PlaceId = GoogleSydneyOfficePlaceId
+            };
+
+            var result = await GoogleMaps.PlacesDetails.QueryAsync(request);
+
+            AssertInconclusive.NotExceedQuota(result);
+            Assert.That(result.Status, Is.EqualTo(Status.OK));
+
+            // Extract country using the helper method
+            var country = result.Result.GetCountry();
+            var countryShort = result.Result.GetCountry(useShortName: true);
+            
+            Assert.That(country, Is.Not.Null.And.Not.Empty);
+            Assert.That(countryShort, Is.Not.Null.And.Not.Empty);
+            Assert.That(countryShort, Is.EqualTo("AU"));
+        }
+    }
+}
diff --git a/GoogleMapsApi/Entities/PlacesDetails/Response/Result.cs b/GoogleMapsApi/Entities/PlacesDetails/Response/Result.cs
@@ -2,6 +2,7 @@
 using System.Globalization;
 using System.Runtime.Serialization;
 using System.Collections.Generic;
+using System.Linq;
 using GoogleMapsApi.Entities.Common;
 
 namespace GoogleMapsApi.Entities.PlacesDetails.Response
@@ -13,6 +14,11 @@ public class Result
         /// name contains the human-readable name for the returned result. For establishment results, this is usually the canonicalized business name.
         /// </summary>
     
+        /// <summary>
+        /// address_components is an array containing the separate address components.
+        /// Use the helper methods on this Result class to easily extract street address, state, postal code, etc.
+        /// Example: result.GetStreetAddress(), result.GetState(), result.GetPostalCode()
+        /// </summary>
         [DataMember(Name="address_components")]
         public IEnumerable<GoogleMapsApi.Entities.Geocoding.Response.AddressComponent> AddressComponent { get; set; }
 
@@ -228,6 +234,164 @@ internal string string_PriceLevel
 
         [DataMember(Name = "place_id")]
         public string PlaceId { get; set; }
+
+        #region Address Component Helper Methods
+
+        /// <summary>
+        /// Gets the street address (street number + route) from address components
+        /// </summary>
+        /// <returns>Street address or null if not found</returns>
+        public string GetStreetAddress()
+        {
+            if (AddressComponent == null)
+                return null;
+
+            var streetNumber = GetAddressComponentByType("street_number")?.LongName;
+            var route = GetAddressComponentByType("route")?.LongName;
+
+            if (string.IsNullOrEmpty(streetNumber) && string.IsNullOrEmpty(route))
+                return null;
+
+            if (string.IsNullOrEmpty(streetNumber))
+                return route;
+
+            if (string.IsNullOrEmpty(route))
+                return streetNumber;
+
+            return $"{streetNumber} {route}";
+        }
+
+        /// <summary>
+        /// Gets the state/province from address components
+        /// </summary>
+        /// <param name="useShortName">If true, returns short name (e.g., "NY"), otherwise long name (e.g., "New York")</param>
+        /// <returns>State/province or null if not found</returns>
+        public string GetState(bool useShortName = false)
+        {
+            if (AddressComponent == null)
+                return null;
+
+            var component = GetAddressComponentByType("administrative_area_level_1");
+            return component == null ? null : (useShortName ? component.ShortName : component.LongName);
+        }
+
+        /// <summary>
+        /// Gets the postal code from address components
+        /// </summary>
+        /// <returns>Postal code or null if not found</returns>
+        public string GetPostalCode()
+        {
+            if (AddressComponent == null)
+                return null;
+
+            return GetAddressComponentByType("postal_code")?.LongName;
+        }
+
+        /// <summary>
+        /// Gets the city/locality from address components
+        /// </summary>
+        /// <param name="useShortName">If true, returns short name, otherwise long name</param>
+        /// <returns>City/locality or null if not found</returns>
+        public string GetCity(bool useShortName = false)
+        {
+            if (AddressComponent == null)
+                return null;
+
+            // Try locality first, then sublocality
+            var component = GetAddressComponentByType("locality") 
+                          ?? GetAddressComponentByType("sublocality");
+            
+            return component == null ? null : (useShortName ? component.ShortName : component.LongName);
+        }
+
+        /// <summary>
+        /// Gets the country from address components
+        /// </summary>
+        /// <param name="useShortName">If true, returns short name (e.g., "US"), otherwise long name (e.g., "United States")</param>
+        /// <returns>Country or null if not found</returns>
+        public string GetCountry(bool useShortName = false)
+        {
+            if (AddressComponent == null)
+                return null;
+
+            var component = GetAddressComponentByType("country");
+            return component == null ? null : (useShortName ? component.ShortName : component.LongName);
+        }
+
+        /// <summary>
+        /// Gets a complete address breakdown from address components
+        /// </summary>
+        /// <returns>Address breakdown object</returns>
+        public AddressBreakdown GetAddressBreakdown()
+        {
+            if (AddressComponent == null)
+                return new AddressBreakdown();
+
+            return new AddressBreakdown
+            {
+                StreetAddress = GetStreetAddress(),
+                City = GetCity(),
+                State = GetState(),
+                PostalCode = GetPostalCode(),
+                Country = GetCountry()
+            };
+        }
+
+        /// <summary>
+        /// Helper method to find an address component by type
+        /// </summary>
+        /// <param name="type">The type to search for</param>
+        /// <returns>Address component or null if not found</returns>
+        private GoogleMapsApi.Entities.Geocoding.Response.AddressComponent GetAddressComponentByType(string type)
+        {
+            return AddressComponent?.FirstOrDefault(ac => ac.Types?.Contains(type) == true);
+        }
+
+        #endregion
+    }
+
+    /// <summary>
+    /// Represents a complete address breakdown with individual components
+    /// </summary>
+    public class AddressBreakdown
+    {
+        /// <summary>
+        /// Street address (street number + route)
+        /// </summary>
+        public string StreetAddress { get; set; }
+
+        /// <summary>
+        /// City/locality
+        /// </summary>
+        public string City { get; set; }
+
+        /// <summary>
+        /// State/province
+        /// </summary>
+        public string State { get; set; }
+
+        /// <summary>
+        /// Postal code
+        /// </summary>
+        public string PostalCode { get; set; }
+
+        /// <summary>
+        /// Country
+        /// </summary>
+        public string Country { get; set; }
+
+        /// <summary>
+        /// Returns a formatted address string
+        /// </summary>
+        /// <returns>Formatted address</returns>
+        public override string ToString()
+        {
+            var parts = new[] { StreetAddress, City, State, PostalCode, Country }
+                .Where(part => !string.IsNullOrEmpty(part))
+                .ToArray();
+
+            return string.Join(", ", parts);
+        }
     }
 
     public enum PriceLevel
diff --git a/GoogleMapsApi/Examples/PlacesDetailsAddressExtractionExample.cs b/GoogleMapsApi/Examples/PlacesDetailsAddressExtractionExample.cs
