feat(trimble): add Trimble Maps geocoding provider with forward and reverse geocoding support

Geo.NET.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.1.32421.90
+# Visual Studio Version 18
+VisualStudioVersion = 18.3.11520.95 d18.3
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SolutionItems", "SolutionItems", "{B3BD11A7-1752-49E3-AE50-A65B5FE7B7B2}"
 	ProjectSection(SolutionItems) = preProject
@@ -53,6 +53,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Geo.Positionstack", "src\Ge
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Geo.Positionstack.Tests", "test\Geo.Positionstack.Tests\Geo.Positionstack.Tests.csproj", "{E09BD60D-6E8A-4210-9274-695A2DFFE976}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Geo.Trimble", "src\Geo.Trimble\Geo.Trimble.csproj", "{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Geo.Trimble.Tests", "test\Geo.Trimble.Tests\Geo.Trimble.Tests.csproj", "{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -131,6 +135,14 @@ Global
 		{E09BD60D-6E8A-4210-9274-695A2DFFE976}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E09BD60D-6E8A-4210-9274-695A2DFFE976}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E09BD60D-6E8A-4210-9274-695A2DFFE976}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -154,6 +166,8 @@ Global
 		{1A320DE3-B14B-46EE-A0E6-C6783E585F73} = {67253D97-9FC9-4749-80DC-A5D84339DC05}
 		{03C7B4AE-7905-4292-8133-3F4AA6EDCA3A} = {8F3BA9BC-542C-450C-96C9-F0D72FECC930}
 		{E09BD60D-6E8A-4210-9274-695A2DFFE976} = {67253D97-9FC9-4749-80DC-A5D84339DC05}
+		{7F4A2E61-83B1-4C2D-9A5E-1D3F8B7C4E90} = {8F3BA9BC-542C-450C-96C9-F0D72FECC930}
+		{B2D5A7F3-6E1C-4B9A-8D2F-3C7E5A1B4D60} = {67253D97-9FC9-4749-80DC-A5D84339DC05}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {C4B688C4-40EC-4577-9EB2-4CF2412DA0B1}

src/Geo.Trimble/Abstractions/ITrimbleGeocoding.cs

@@ -0,0 +1,38 @@
+// <copyright file="ITrimbleGeocoding.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Trimble
+{
+    using System.Collections.Generic;
+    using System.Threading;
+    using System.Threading.Tasks;
+    using Geo.Core.Models.Exceptions;
+    using Geo.Trimble.Models.Parameters;
+    using Geo.Trimble.Models.Responses;
+
+    /// <summary>
+    /// An interface for calling the Trimble Maps geocoding methods.
+    /// </summary>
+    public interface ITrimbleGeocoding
+    {
+        /// <summary>
+        /// Calls the Trimble Maps geocoding API and returns the results.
+        /// </summary>
+        /// <param name="parameters">A <see cref="GeocodingParameters"/> with the parameters of the request.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to cancel the request.</param>
+        /// <returns>A list of <see cref="GeocodeResponse"/> with the response from Trimble Maps.</returns>
+        /// <exception cref="GeoNETException">Thrown for multiple different reasons. Check the inner exception for more information.</exception>
+        Task<IList<GeocodeResponse>> GeocodingAsync(GeocodingParameters parameters, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Calls the Trimble Maps reverse geocoding API and returns the results.
+        /// </summary>
+        /// <param name="parameters">A <see cref="ReverseGeocodingParameters"/> with the parameters of the request.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to cancel the request.</param>
+        /// <returns>A <see cref="GeocodeResponse"/> with the response from Trimble Maps.</returns>
+        /// <exception cref="GeoNETException">Thrown for multiple different reasons. Check the inner exception for more information.</exception>
+        Task<GeocodeResponse> ReverseGeocodingAsync(ReverseGeocodingParameters parameters, CancellationToken cancellationToken = default);
+    }
+}

src/Geo.Trimble/DependencyInjection/ServiceCollectionExtensions.cs

@@ -0,0 +1,44 @@
+// <copyright file="ServiceCollectionExtensions.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Extensions.DependencyInjection
+{
+    using System;
+    using Geo.Trimble;
+    using Geo.Trimble.Services;
+    using Microsoft.Extensions.DependencyInjection;
+    using Microsoft.Extensions.Options;
+
+    /// <summary>
+    /// Extension methods for the <see cref="IServiceCollection"/> class.
+    /// </summary>
+    public static class ServiceCollectionExtensions
+    {
+        /// <summary>
+        /// Adds the Trimble Maps geocoding services to the service collection.
+        /// <para>
+        /// Adds the services:
+        /// <list type="bullet">
+        /// <item><see cref="IOptions{TOptions}"/> of <see cref="ITrimbleGeocoding"/></item>
+        /// <item><see cref="ITrimbleGeocoding"/></item>
+        /// </list>
+        /// </para>
+        /// </summary>
+        /// <param name="services">An <see cref="IServiceCollection"/> to add the Trimble Maps services to.</param>
+        /// <returns>An <see cref="KeyBuilder{T}"/> to configure the Trimble Maps geocoding.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="services"/> is null.</exception>
+        public static KeyBuilder<ITrimbleGeocoding> AddTrimbleGeocoding(this IServiceCollection services)
+        {
+            if (services == null)
+            {
+                throw new ArgumentNullException(nameof(services));
+            }
+
+            services.AddKeyOptions<ITrimbleGeocoding>();
+
+            return new KeyBuilder<ITrimbleGeocoding>(services.AddHttpClient<ITrimbleGeocoding, TrimbleGeocoding>());
+        }
+    }
+}

src/Geo.Trimble/Extensions/LoggerExtensions.cs

@@ -0,0 +1,62 @@
+// <copyright file="LoggerExtensions.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Trimble
+{
+    using System;
+    using Geo.Trimble.Services;
+    using Microsoft.Extensions.Logging;
+
+    /// <summary>
+    /// Extension methods for the <see cref="ILogger"/> class.
+    /// </summary>
+    internal static class LoggerExtensions
+    {
+        private static readonly Action<ILogger, string, Exception> _error = LoggerMessage.Define<string>(
+            LogLevel.Error,
+            new EventId(1, nameof(TrimbleGeocoding)),
+            "TrimbleGeocoding: {ErrorMessage}");
+
+        private static readonly Action<ILogger, string, Exception> _warning = LoggerMessage.Define<string>(
+            LogLevel.Warning,
+            new EventId(2, nameof(TrimbleGeocoding)),
+            "TrimbleGeocoding: {WarningMessage}");
+
+        private static readonly Action<ILogger, string, Exception> _debug = LoggerMessage.Define<string>(
+            LogLevel.Debug,
+            new EventId(3, nameof(TrimbleGeocoding)),
+            "TrimbleGeocoding: {DebugMessage}");
+
+        /// <summary>
+        /// "TrimbleGeocoding: {ErrorMessage}".
+        /// </summary>
+        /// <param name="logger">An <see cref="ILogger"/> used to log the error message.</param>
+        /// <param name="errorMessage">The error message to log.</param>
+        public static void TrimbleError(this ILogger logger, string errorMessage)
+        {
+            _error(logger, errorMessage, null);
+        }
+
+        /// <summary>
+        /// "TrimbleGeocoding: {WarningMessage}".
+        /// </summary>
+        /// <param name="logger">An <see cref="ILogger"/> used to log the warning message.</param>
+        /// <param name="warningMessage">The warning message to log.</param>
+        public static void TrimbleWarning(this ILogger logger, string warningMessage)
+        {
+            _warning(logger, warningMessage, null);
+        }
+
+        /// <summary>
+        /// "TrimbleGeocoding: {DebugMessage}".
+        /// </summary>
+        /// <param name="logger">An <see cref="ILogger"/> used to log the debug message.</param>
+        /// <param name="debugMessage">The debug message to log.</param>
+        public static void TrimbleDebug(this ILogger logger, string debugMessage)
+        {
+            _debug(logger, debugMessage, null);
+        }
+    }
+}

src/Geo.Trimble/Geo.Trimble.csproj

@@ -0,0 +1,45 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0;net6.0;net8.0;net10.0</TargetFrameworks>
+    <Authors>Justin Canton</Authors>
+    <Company>Geo.NET</Company>
+    <Product>Geo.NET Trimble</Product>
+    <PackageTags>geocoding geo.net Trimble</PackageTags>
+    <Description>A lightweight method for communicating with the Trimble Maps geocoding APIs. This includes models and interfaces for calling Trimble Maps.</Description>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <RepositoryUrl>https://github.com/JustinCanton/Geo.NET</RepositoryUrl>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+  </PropertyGroup>
+
+  <Import Project="..\Source.props" />
+
+  <ItemGroup>
+    <ProjectReference Include="..\Geo.Core\Geo.Core.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Compile Update="Resources\Services\TrimbleGeocoding.Designer.cs">
+      <DesignTime>True</DesignTime>
+      <AutoGen>True</AutoGen>
+      <DependentUpon>TrimbleGeocoding.resx</DependentUpon>
+    </Compile>
+  </ItemGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Update="Resources\Services\TrimbleGeocoding.resx">
+      <Generator>ResXFileCodeGenerator</Generator>
+      <LastGenOutput>TrimbleGeocoding.Designer.cs</LastGenOutput>
+    </EmbeddedResource>
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="README.md">
+      <Pack>True</Pack>
+      <PackagePath>\</PackagePath>
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

src/Geo.Trimble/Models/Enums/CountryAbbrevType.cs

@@ -0,0 +1,28 @@
+// <copyright file="CountryAbbrevType.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Trimble.Models.Enums
+{
+    /// <summary>
+    /// The format used for country abbreviations in Trimble Maps API responses.
+    /// </summary>
+    public enum CountryAbbrevType
+    {
+        /// <summary>FIPS country code.</summary>
+        FIPS,
+
+        /// <summary>ISO 3166-1 alpha-2 (two-letter) country code.</summary>
+        ISO2,
+
+        /// <summary>ISO 3166-1 alpha-3 (three-letter) country code.</summary>
+        ISO3,
+
+        /// <summary>GENC two-letter country code.</summary>
+        GENC2,
+
+        /// <summary>GENC three-letter country code.</summary>
+        GENC3,
+    }
+}

src/Geo.Trimble/Models/Enums/Region.cs

@@ -0,0 +1,37 @@
+// <copyright file="Region.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Trimble.Models.Enums
+{
+    /// <summary>
+    /// The geographic region used to scope Trimble Maps API requests.
+    /// </summary>
+    public enum Region
+    {
+        /// <summary>North America (default).</summary>
+        NorthAmerica = 0,
+
+        /// <summary>Africa.</summary>
+        Africa = 1,
+
+        /// <summary>Asia.</summary>
+        Asia = 2,
+
+        /// <summary>Europe.</summary>
+        Europe = 3,
+
+        /// <summary>Oceania.</summary>
+        Oceania = 4,
+
+        /// <summary>South America.</summary>
+        SouthAmerica = 5,
+
+        /// <summary>Middle East.</summary>
+        MiddleEast = 6,
+
+        /// <summary>Global.</summary>
+        Global = 7,
+    }
+}

src/Geo.Trimble/Models/Parameters/Coordinate.cs

@@ -0,0 +1,31 @@
+// <copyright file="Coordinate.cs" company="Geo.NET">
+// Copyright (c) Geo.NET.
+// Licensed under the MIT license. See the LICENSE file in the solution root for full license information.
+// </copyright>
+
+namespace Geo.Trimble.Models.Parameters
+{
+    using System.Globalization;
+
+    /// <summary>
+    /// The coordinates (longitude, latitude) used for Trimble Maps reverse geocoding.
+    /// </summary>
+    public class Coordinate
+    {
+        /// <summary>
+        /// Gets or sets the latitude of the location. For example: "40.7128".
+        /// </summary>
+        public double Latitude { get; set; }
+
+        /// <summary>
+        /// Gets or sets the longitude of the location. For example: "-74.0060".
+        /// </summary>
+        public double Longitude { get; set; }
+
+        /// <inheritdoc/>
+        public override string ToString()
+        {
+            return string.Format(CultureInfo.InvariantCulture, "{0},{1}", Longitude, Latitude);
+        }
+    }
+}