Remove HERE legacy credential flow

Root cause: the branch briefly restored the retired HERE app_id/app_code path even though this major-version line is meant to standardize on the current API-key-based Geocoding and Search API.

Remove the legacy HERE constructor, parsing models, sample/test config, and docs so the public surface matches the intended breaking-change direction.

Author: niemyjski

README.md

@@ -1,13 +1,13 @@
 # Generic C# Geocoding API [![CI](https://github.com/exceptionless/Geocoding.net/actions/workflows/build.yml/badge.svg)](https://github.com/exceptionless/Geocoding.net/actions/workflows/build.yml) [![CodeQL](https://github.com/exceptionless/Geocoding.net/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/exceptionless/Geocoding.net/actions/workflows/codeql-analysis.yml)
 
-Includes a model and interface for communicating with current geocoding providers while preserving selected legacy compatibility surfaces.
+Includes a model and interface for communicating with current geocoding providers.
 
 | Provider | Package | Status | Auth | Notes |
 | --- | --- | --- | --- | --- |
 | 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 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. |
+| HERE Geocoding and Search | `Geocoding.Here` | Supported | HERE API key | Uses the current HERE Geocoding and Search API. |
 | 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,9 @@ 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 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.
+HERE supports a [HERE API key](https://www.here.com/docs/category/identity-and-access-management) for the current Geocoding and Search API.
+
+The current major-version line no longer supports HERE `app_id`/`app_code` credentials. Migrate existing HERE integrations to API keys before upgrading.
 
 Yahoo still uses the legacy OAuth consumer key and consumer secret flow, but onboarding remains unverified and the package is deprecated.
 
@@ -93,7 +95,7 @@ Alternatively, if you are on Windows, you can open the solution in [Visual Studi
 
 ### Service 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.
+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. 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 +107,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`, `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`.
+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`.

samples/Example.Web/Program.cs

@@ -117,8 +117,7 @@ static string[] GetConfiguredProviders(ProviderOptions options)
 
     configuredProviders.Add("google");
 
-    if (!String.IsNullOrWhiteSpace(options.Here.ApiKey)
-        || (!String.IsNullOrWhiteSpace(options.Here.AppId) && !String.IsNullOrWhiteSpace(options.Here.AppCode)))
+    if (!String.IsNullOrWhiteSpace(options.Here.ApiKey))
         configuredProviders.Add("here");
 
     if (!String.IsNullOrWhiteSpace(options.MapQuest.ApiKey))
@@ -163,23 +162,16 @@ static bool TryCreateGeocoder(string provider, ProviderOptions options, out IGeo
             return true;
 
         case "here":
-            if (!String.IsNullOrWhiteSpace(options.Here.ApiKey))
-            {
-                geocoder = new HereGeocoder(options.Here.ApiKey);
-                error = null;
-                return true;
-            }
-
-            if (!String.IsNullOrWhiteSpace(options.Here.AppId) && !String.IsNullOrWhiteSpace(options.Here.AppCode))
+            geocoder = default!;
+            if (String.IsNullOrWhiteSpace(options.Here.ApiKey))
             {
-                geocoder = new HereGeocoder(options.Here.AppId, options.Here.AppCode);
-                error = null;
-                return true;
+                error = "Configure Providers:Here:ApiKey before using the HERE provider.";
+                return false;
             }
 
-            geocoder = default!;
-            error = "Configure Providers:Here:ApiKey, or provide both Providers:Here:AppId and Providers:Here:AppCode, before using the HERE provider.";
-            return false;
+            geocoder = new HereGeocoder(options.Here.ApiKey);
+            error = null;
+            return true;
 
         case "mapquest":
             if (String.IsNullOrWhiteSpace(options.MapQuest.ApiKey))
@@ -266,8 +258,6 @@ internal sealed class GoogleProviderOptions
 internal sealed class HereProviderOptions
 {
     public String ApiKey { get; init; } = String.Empty;
-    public String AppId { get; init; } = String.Empty;
-    public String AppCode { get; init; } = String.Empty;
 }
 
 internal sealed class MapQuestProviderOptions

samples/Example.Web/appsettings.json

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

src/Geocoding.Here/HereGeocoder.cs

@@ -1,11 +1,9 @@
 using System.Globalization;
 using System.Net;
 using System.Net.Http;
-using System.Runtime.Serialization.Json;
 using System.Text;
 using System.Text.Json;
 using System.Text.Json.Serialization;
-using HereJson = Geocoding.Here.Json;
 
 namespace Geocoding.Here;
 
@@ -19,13 +17,8 @@ public class HereGeocoder : IGeocoder
 {
     private const string BaseAddress = "https://geocode.search.hereapi.com/v1/geocode";
     private const string ReverseBaseAddress = "https://revgeocode.search.hereapi.com/v1/revgeocode";
-    private const string LegacyBaseAddress = "https://geocoder.api.here.com/6.2/geocode.json?app_id={0}&app_code={1}&{2}";
-    private const string LegacyReverseBaseAddress = "https://reverse.geocoder.api.here.com/6.2/reversegeocode.json?app_id={0}&app_code={1}&mode=retrieveAddresses&{2}";
 
-    private readonly string? _apiKey;
-    private readonly string? _legacyAppId;
-    private readonly string? _legacyAppCode;
-    private bool UsesLegacyCredentials => !String.IsNullOrWhiteSpace(_legacyAppId) && !String.IsNullOrWhiteSpace(_legacyAppCode);
+    private readonly string _apiKey;
 
     /// <summary>
     /// Gets or sets the proxy used for HERE requests.
@@ -56,28 +49,8 @@ public HereGeocoder(string apiKey)
         _apiKey = apiKey;
     }
 
-    /// <summary>
-    /// Initializes a new instance of the <see cref="HereGeocoder"/> class using the deprecated app_id/app_code signature.
-    /// </summary>
-    /// <param name="appId">The deprecated HERE application identifier.</param>
-    /// <param name="appCode">The deprecated HERE application code.</param>
-    public HereGeocoder(string appId, string appCode)
-    {
-        if (String.IsNullOrWhiteSpace(appId))
-            throw new ArgumentException("appId can not be null or empty.", nameof(appId));
-
-        if (String.IsNullOrWhiteSpace(appCode))
-            throw new ArgumentException("appCode can not be null or empty.", nameof(appCode));
-
-        _legacyAppId = appId;
-        _legacyAppCode = appCode;
-    }
-
     private Uri GetQueryUrl(string address)
     {
-        if (UsesLegacyCredentials)
-            return GetLegacyQueryUrl(("searchtext", address));
-
         var parameters = CreateBaseParameters();
         parameters.Add(new KeyValuePair<string, string>("q", address));
         AppendGlobalParameters(parameters, includeAtBias: true);
@@ -86,30 +59,17 @@ private Uri GetQueryUrl(string address)
 
     private Uri GetQueryUrl(string street, string city, string state, string postalCode, string country)
     {
-        if (new[] { street, city, state, postalCode, country }.All(part => String.IsNullOrWhiteSpace(part)))
-            throw new ArgumentException("At least one address component is required.");
-
-        if (UsesLegacyCredentials)
-        {
-            return GetLegacyQueryUrl(
-                ("street", street),
-                ("city", city),
-                ("state", state),
-                ("postalcode", postalCode),
-                ("country", country));
-        }
-
         var query = String.Join(", ", new[] { street, city, state, postalCode, country }
             .Where(part => !String.IsNullOrWhiteSpace(part)));
 
+        if (String.IsNullOrWhiteSpace(query))
+            throw new ArgumentException("At least one address component is required.");
+
         return GetQueryUrl(query);
     }
 
     private Uri GetQueryUrl(double latitude, double longitude)
     {
-        if (UsesLegacyCredentials)
-            return GetLegacyReverseQueryUrl(latitude, longitude);
-
         var parameters = CreateBaseParameters();
         parameters.Add(new KeyValuePair<string, string>("at", String.Format(CultureInfo.InvariantCulture, "{0},{1}", latitude, longitude)));
         AppendGlobalParameters(parameters, includeAtBias: false);
@@ -129,67 +89,6 @@ private List<KeyValuePair<string, string>> CreateBaseParameters()
         return parameters;
     }
 
-    private Uri GetLegacyQueryUrl(params (string Key, string Value)[] values)
-    {
-        var parameters = CreateLegacyBaseParameters(includeProxBias: true);
-        foreach (var (key, value) in values)
-        {
-            if (!String.IsNullOrWhiteSpace(value))
-                parameters.Add(new KeyValuePair<string, string>(key, value));
-        }
-
-        return BuildLegacyUri(LegacyBaseAddress, parameters);
-    }
-
-    private Uri GetLegacyReverseQueryUrl(double latitude, double longitude)
-    {
-        var parameters = CreateLegacyBaseParameters(includeProxBias: false);
-        parameters.Add(new KeyValuePair<string, string>("prox", FormatLegacyCoordinate(latitude, longitude)));
-        return BuildLegacyUri(LegacyReverseBaseAddress, parameters);
-    }
-
-    private List<KeyValuePair<string, string>> CreateLegacyBaseParameters(bool includeProxBias)
-    {
-        var parameters = new List<KeyValuePair<string, string>>();
-
-        if (includeProxBias && UserLocation is not null)
-            parameters.Add(new KeyValuePair<string, string>("prox", FormatLegacyCoordinate(UserLocation.Latitude, UserLocation.Longitude)));
-
-        if (UserMapView is not null)
-        {
-            parameters.Add(new KeyValuePair<string, string>(
-                "mapview",
-                FormatLegacyBounds(UserMapView)));
-        }
-
-        if (MaxResults is > 0)
-            parameters.Add(new KeyValuePair<string, string>("maxresults", MaxResults.Value.ToString(CultureInfo.InvariantCulture)));
-
-        return parameters;
-    }
-
-    private Uri BuildLegacyUri(string baseAddress, IEnumerable<KeyValuePair<string, string>> parameters)
-    {
-        var url = String.Format(CultureInfo.InvariantCulture, baseAddress, UrlEncode(_legacyAppId!), UrlEncode(_legacyAppCode!), BuildQueryString(parameters));
-        return new Uri(url);
-    }
-
-    private static string FormatLegacyCoordinate(double latitude, double longitude)
-    {
-        return String.Format(CultureInfo.InvariantCulture, "{0},{1}", latitude, longitude);
-    }
-
-    private static string FormatLegacyBounds(Bounds bounds)
-    {
-        return String.Format(
-            CultureInfo.InvariantCulture,
-            "{0},{1},{2},{3}",
-            bounds.SouthWest.Latitude,
-            bounds.SouthWest.Longitude,
-            bounds.NorthEast.Latitude,
-            bounds.NorthEast.Longitude);
-    }
-
     private void AppendGlobalParameters(ICollection<KeyValuePair<string, string>> parameters, bool includeAtBias)
     {
         if (includeAtBias && UserLocation is not null)
@@ -242,12 +141,6 @@ private string BuildQueryString(IEnumerable<KeyValuePair<string, string>> parame
         try
         {
             var url = GetQueryUrl(address);
-            if (UsesLegacyCredentials)
-            {
-                var legacyResponse = await GetLegacyResponse(url, cancellationToken).ConfigureAwait(false);
-                return ParseLegacyResponse(legacyResponse);
-            }
-
             var response = await GetResponse(url, cancellationToken).ConfigureAwait(false);
             return ParseResponse(response);
         }
@@ -263,12 +156,6 @@ private string BuildQueryString(IEnumerable<KeyValuePair<string, string>> parame
         try
         {
             var url = GetQueryUrl(street, city, state, postalCode, country);
-            if (UsesLegacyCredentials)
-            {
-                var legacyResponse = await GetLegacyResponse(url, cancellationToken).ConfigureAwait(false);
-                return ParseLegacyResponse(legacyResponse);
-            }
-
             var response = await GetResponse(url, cancellationToken).ConfigureAwait(false);
             return ParseResponse(response);
         }
@@ -293,12 +180,6 @@ private string BuildQueryString(IEnumerable<KeyValuePair<string, string>> parame
         try
         {
             var url = GetQueryUrl(latitude, longitude);
-            if (UsesLegacyCredentials)
-            {
-                var legacyResponse = await GetLegacyResponse(url, cancellationToken).ConfigureAwait(false);
-                return ParseLegacyResponse(legacyResponse);
-            }
-
             var response = await GetResponse(url, cancellationToken).ConfigureAwait(false);
             return ParseResponse(response);
         }
@@ -380,27 +261,6 @@ private async Task<HereResponse> GetResponse(Uri queryUrl, CancellationToken can
         return JsonSerializer.Deserialize<HereResponse>(json, Extensions.JsonOptions) ?? new HereResponse();
     }
 
-    private async Task<HereJson.Response> GetLegacyResponse(Uri queryUrl, CancellationToken cancellationToken)
-    {
-        using var client = BuildClient();
-        using var request = CreateRequest(queryUrl);
-        using var response = await client.SendAsync(request, cancellationToken).ConfigureAwait(false);
-        using var stream = await response.Content.ReadAsStreamAsync().ConfigureAwait(false);
-
-        var serializer = new DataContractJsonSerializer(typeof(HereJson.ServerResponse));
-        var payload = (HereJson.ServerResponse?)serializer.ReadObject(stream);
-        if (payload is null)
-            return new HereJson.Response { View = Array.Empty<HereJson.View>() };
-
-        if (!String.IsNullOrWhiteSpace(payload.ErrorType))
-        {
-            var errorType = payload.ErrorType!;
-            throw new HereGeocodingException(payload.Details ?? errorType, errorType, payload.ErrorSubtype ?? errorType);
-        }
-
-        return payload.Response ?? new HereJson.Response { View = Array.Empty<HereJson.View>() };
-    }
-
     private static HereLocationType MapLocationType(string? resultType)
     {
         switch (resultType?.Trim().ToLowerInvariant())
@@ -425,42 +285,6 @@ private static HereLocationType MapLocationType(string? resultType)
         }
     }
 
-    private IEnumerable<HereAddress> ParseLegacyResponse(HereJson.Response response)
-    {
-        if (response.View is null)
-            yield break;
-
-        foreach (var view in response.View)
-        {
-            if (view?.Result is null)
-                continue;
-
-            foreach (var result in view.Result)
-            {
-                if (result?.Location is null)
-                    continue;
-
-                var location = result.Location;
-                if (location.DisplayPosition is null)
-                    continue;
-
-                if (!Enum.TryParse(location.LocationType, true, out HereLocationType locationType))
-                    locationType = HereLocationType.Unknown;
-
-                yield return new HereAddress(
-                    location.Address?.Label ?? location.Name ?? String.Empty,
-                    new Location(location.DisplayPosition.Latitude, location.DisplayPosition.Longitude),
-                    location.Address?.Street,
-                    location.Address?.HouseNumber,
-                    location.Address?.City,
-                    location.Address?.State,
-                    location.Address?.PostalCode,
-                    location.Address?.Country,
-                    locationType);
-            }
-        }
-    }
-
     private string UrlEncode(string toEncode)
     {
         if (String.IsNullOrEmpty(toEncode))