Restore provider compatibility surfaces

The remaining review feedback traced back to public compatibility breaks and stale repo wiring around legacy provider paths. This restores HERE legacy credential support, hardens provider request construction, preserves Google enum values, and realigns docs/tests/sample config with the supported compatibility surface.

Author: niemyjski

README.md

@@ -7,7 +7,7 @@ Includes a model and interface for communicating with current geocoding provider
 | Google Maps | `Geocoding.Google` | Supported | API key or signed client credentials | `BusinessKey` supports signed Google Maps client-based requests when your deployment requires them. |
 | Azure Maps | `Geocoding.Microsoft` | Supported | Azure Maps subscription key | Primary Microsoft-backed geocoder. |
 | Bing Maps | `Geocoding.Microsoft` | Deprecated compatibility | Bing Maps enterprise key | `BingMapsGeocoder` remains available for existing consumers and is marked obsolete for new development. |
-| HERE Geocoding and Search | `Geocoding.Here` | Supported | HERE API key | Uses the current HERE Geocoding and Search API. |
+| HERE Geocoding and Search | `Geocoding.Here` | Supported | HERE API key or legacy app_id/app_code | Uses the current HERE Geocoding and Search API when an API key is configured and retains the legacy credential flow for compatibility. |
 | MapQuest | `Geocoding.MapQuest` | Supported | API key | Commercial API only. OpenStreetMap mode is no longer supported. |
 | Yahoo PlaceFinder/BOSS | `Geocoding.Yahoo` | Deprecated | OAuth consumer key + secret | Legacy package retained for compatibility, but the service remains deprecated and unverified. |
 
@@ -76,7 +76,7 @@ Bing Maps requires an existing Bing Maps enterprise key. The provider is depreca
 
 MapQuest requires a [developer API key](https://developer.mapquest.com/user/me/apps).
 
-HERE requires a [HERE API key](https://www.here.com/docs/category/identity-and-access-management).
+HERE supports a [HERE API key](https://www.here.com/docs/category/identity-and-access-management) for the current Geocoding and Search API. Existing consumers can also continue using the legacy `app_id`/`app_code` constructor for compatibility.
 
 Yahoo still uses the legacy OAuth consumer key and consumer secret flow, but onboarding remains unverified and the package is deprecated.
 
@@ -93,7 +93,7 @@ Alternatively, if you are on Windows, you can open the solution in [Visual Studi
 
 ### Service Tests
 
-You will need to generate API keys for each respective service to run the service tests. Make a `settings-override.json` as a copy of `settings.json` in the test project and put in your API keys. Then you should be able to run the tests.
+You will need credentials for each respective service to run the service tests. Make a `settings-override.json` as a copy of `settings.json` in the test project and put in your provider credentials there. For HERE, that can be either `Providers:Here:ApiKey` or the legacy `Providers:Here:AppId` plus `Providers:Here:AppCode` pair. Then you should be able to run the tests.
 
 Most provider-backed integration tests skip with a message indicating which setting is required when credentials are missing. The Yahoo suite now follows the same credential gating, but the provider remains deprecated and unverified.
 
@@ -105,4 +105,4 @@ The sample app in `samples/Example.Web` is an ASP.NET Core 10 minimal API that c
 dotnet run --project samples/Example.Web/Example.Web.csproj
 ```
 
-Configure a provider in `samples/Example.Web/appsettings.json` or via environment variables such as `Providers__Azure__ApiKey`, `Providers__Bing__ApiKey`, `Providers__Google__ApiKey`, `Providers__Here__ApiKey`, or `Providers__MapQuest__ApiKey`. Once the app is running, use `samples/Example.Web/sample.http` to call `/providers`, `/geocode`, and `/reverse`.
+Configure a provider in `samples/Example.Web/appsettings.json` or via environment variables such as `Providers__Azure__ApiKey`, `Providers__Bing__ApiKey`, `Providers__Google__ApiKey`, `Providers__Here__ApiKey`, `Providers__Here__AppId`, `Providers__Here__AppCode`, or `Providers__MapQuest__ApiKey`. Once the app is running, use `samples/Example.Web/sample.http` to call `/providers`, `/geocode`, and `/reverse`.

samples/Example.Web/Program.cs

@@ -117,7 +117,8 @@ static string[] GetConfiguredProviders(ProviderOptions options)
 
     configuredProviders.Add("google");
 
-    if (!String.IsNullOrWhiteSpace(options.Here.ApiKey))
+    if (!String.IsNullOrWhiteSpace(options.Here.ApiKey)
+        || (!String.IsNullOrWhiteSpace(options.Here.AppId) && !String.IsNullOrWhiteSpace(options.Here.AppCode)))
         configuredProviders.Add("here");
 
     if (!String.IsNullOrWhiteSpace(options.MapQuest.ApiKey))
@@ -162,23 +163,23 @@ static bool TryCreateGeocoder(string provider, ProviderOptions options, out IGeo
             return true;
 
         case "here":
-            if (!String.IsNullOrWhiteSpace(options.Here.AppId) || !String.IsNullOrWhiteSpace(options.Here.AppCode))
+            if (!String.IsNullOrWhiteSpace(options.Here.ApiKey))
             {
-                geocoder = default!;
-                error = "HERE now uses Providers:Here:ApiKey. The legacy AppId/AppCode settings are no longer supported.";
-                return false;
+                geocoder = new HereGeocoder(options.Here.ApiKey);
+                error = null;
+                return true;
             }
 
-            if (String.IsNullOrWhiteSpace(options.Here.ApiKey))
+            if (!String.IsNullOrWhiteSpace(options.Here.AppId) && !String.IsNullOrWhiteSpace(options.Here.AppCode))
             {
-                geocoder = default!;
-                error = "Configure Providers:Here:ApiKey before using the HERE provider.";
-                return false;
+                geocoder = new HereGeocoder(options.Here.AppId, options.Here.AppCode);
+                error = null;
+                return true;
             }
 
-            geocoder = new HereGeocoder(options.Here.ApiKey);
-            error = null;
-            return true;
+            geocoder = default!;
+            error = "Configure Providers:Here:ApiKey, or provide both Providers:Here:AppId and Providers:Here:AppCode, before using the HERE provider.";
+            return false;
 
         case "mapquest":
             if (String.IsNullOrWhiteSpace(options.MapQuest.ApiKey))
@@ -247,17 +248,17 @@ internal sealed class ProviderOptions
     public MapQuestProviderOptions MapQuest { get; init; } = new();
 }
 
-internal sealed class GoogleProviderOptions
+internal sealed class AzureProviderOptions
 {
     public String ApiKey { get; init; } = String.Empty;
 }
 
-internal sealed class AzureProviderOptions
+internal sealed class BingProviderOptions
 {
     public String ApiKey { get; init; } = String.Empty;
 }
 
-internal sealed class BingProviderOptions
+internal sealed class GoogleProviderOptions
 {
     public String ApiKey { get; init; } = String.Empty;
 }

samples/Example.Web/appsettings.json

@@ -10,6 +10,8 @@
       "ApiKey": ""
     },
     "Here": {
+      "AppCode": "",
+      "AppId": "",
       "ApiKey": ""
     },
     "MapQuest": {

src/Geocoding.Google/GoogleAddressType.cs

@@ -9,89 +9,89 @@
 public enum GoogleAddressType
 {
     /// <summary>The Unknown value.</summary>
-    Unknown,
+    Unknown = 0,
     /// <summary>The StreetAddress value.</summary>
-    StreetAddress,
+    StreetAddress = 1,
     /// <summary>The Route value.</summary>
-    Route,
+    Route = 2,
     /// <summary>The Intersection value.</summary>
-    Intersection,
+    Intersection = 3,
     /// <summary>The Political value.</summary>
-    Political,
+    Political = 4,
     /// <summary>The Country value.</summary>
-    Country,
+    Country = 5,
     /// <summary>The AdministrativeAreaLevel1 value.</summary>
-    AdministrativeAreaLevel1,
+    AdministrativeAreaLevel1 = 6,
     /// <summary>The AdministrativeAreaLevel2 value.</summary>
-    AdministrativeAreaLevel2,
+    AdministrativeAreaLevel2 = 7,
     /// <summary>The AdministrativeAreaLevel3 value.</summary>
-    AdministrativeAreaLevel3,
+    AdministrativeAreaLevel3 = 8,
     /// <summary>The AdministrativeAreaLevel4 value.</summary>
-    AdministrativeAreaLevel4,
+    AdministrativeAreaLevel4 = 32,
     /// <summary>The AdministrativeAreaLevel5 value.</summary>
-    AdministrativeAreaLevel5,
+    AdministrativeAreaLevel5 = 33,
     /// <summary>The AdministrativeAreaLevel6 value.</summary>
-    AdministrativeAreaLevel6,
+    AdministrativeAreaLevel6 = 34,
     /// <summary>The AdministrativeAreaLevel7 value.</summary>
-    AdministrativeAreaLevel7,
+    AdministrativeAreaLevel7 = 35,
     /// <summary>The ColloquialArea value.</summary>
-    ColloquialArea,
+    ColloquialArea = 9,
     /// <summary>The Locality value.</summary>
-    Locality,
+    Locality = 10,
     /// <summary>The SubLocality value.</summary>
-    SubLocality,
+    SubLocality = 11,
     /// <summary>The Neighborhood value.</summary>
-    Neighborhood,
+    Neighborhood = 12,
     /// <summary>The Premise value.</summary>
-    Premise,
+    Premise = 13,
     /// <summary>The Subpremise value.</summary>
-    Subpremise,
+    Subpremise = 14,
     /// <summary>The PostalCode value.</summary>
-    PostalCode,
+    PostalCode = 15,
     /// <summary>The NaturalFeature value.</summary>
-    NaturalFeature,
+    NaturalFeature = 16,
     /// <summary>The Airport value.</summary>
-    Airport,
+    Airport = 17,
     /// <summary>The Park value.</summary>
-    Park,
+    Park = 18,
     /// <summary>The PointOfInterest value.</summary>
-    PointOfInterest,
+    PointOfInterest = 19,
     /// <summary>The PostBox value.</summary>
-    PostBox,
+    PostBox = 20,
     /// <summary>The StreetNumber value.</summary>
-    StreetNumber,
+    StreetNumber = 21,
     /// <summary>The Floor value.</summary>
-    Floor,
+    Floor = 22,
     /// <summary>The Room value.</summary>
-    Room,
+    Room = 23,
     /// <summary>The PostalTown value.</summary>
-    PostalTown,
+    PostalTown = 24,
     /// <summary>The Establishment value.</summary>
-    Establishment,
+    Establishment = 25,
     /// <summary>The SubLocalityLevel1 value.</summary>
-    SubLocalityLevel1,
+    SubLocalityLevel1 = 26,
     /// <summary>The SubLocalityLevel2 value.</summary>
-    SubLocalityLevel2,
+    SubLocalityLevel2 = 27,
     /// <summary>The SubLocalityLevel3 value.</summary>
-    SubLocalityLevel3,
+    SubLocalityLevel3 = 28,
     /// <summary>The SubLocalityLevel4 value.</summary>
-    SubLocalityLevel4,
+    SubLocalityLevel4 = 29,
     /// <summary>The SubLocalityLevel5 value.</summary>
-    SubLocalityLevel5,
+    SubLocalityLevel5 = 30,
     /// <summary>The PostalCodeSuffix value.</summary>
-    PostalCodeSuffix,
+    PostalCodeSuffix = 31,
     /// <summary>The PostalCodePrefix value.</summary>
-    PostalCodePrefix,
+    PostalCodePrefix = 36,
     /// <summary>The PlusCode value.</summary>
-    PlusCode,
+    PlusCode = 37,
     /// <summary>The Landmark value.</summary>
-    Landmark,
+    Landmark = 38,
     /// <summary>The Parking value.</summary>
-    Parking,
+    Parking = 39,
     /// <summary>The BusStation value.</summary>
-    BusStation,
+    BusStation = 40,
     /// <summary>The TrainStation value.</summary>
-    TrainStation,
+    TrainStation = 41,
     /// <summary>The TransitStation value.</summary>
-    TransitStation
+    TransitStation = 42
 }