JK.IpGeolocation
0.4.2
dotnet add package JK.IpGeolocation --version 0.4.2
NuGet\Install-Package JK.IpGeolocation -Version 0.4.2
<PackageReference Include="JK.IpGeolocation" Version="0.4.2" />
paket add JK.IpGeolocation --version 0.4.2
#r "nuget: JK.IpGeolocation, 0.4.2"
// Install JK.IpGeolocation as a Cake Addin #addin nuget:?package=JK.IpGeolocation&version=0.4.2 // Install JK.IpGeolocation as a Cake Tool #tool nuget:?package=JK.IpGeolocation&version=0.4.2
IpGeolocation
IpGeolocation is a simple library that allows you to get geolocation data based on IP address. It uses ipapi.co API to get the data. The library is written in C# and is available as a NuGet package.
Project structure
- IpGeolocation - IpGeolocation library
- IpGeolocation.ConsoleApp - console application with example use of the IpGeolocation library
- IpGeolocation.ConsoleApp.WithoutConfig - console application with example use of the IpGeolocation library without configuration
- IpGeolocation.Tests - unit tests
Installation
You can install the library via NuGet package manager:
Install-Package JK.IpGeolocation
or .NET CLI:
dotnet add package JK.IpGeolocation
or just copy into the project file to reference the package:
<PackageReference Include="JK.IpGeolocation" Version="0.4.2" />
Usage
To use the library you need to create an instance of the IpGeolocationService
class and call the GetGeolocationData
method with the IP address as an argument. The method returns an instance of the GeolocationData
class with the geolocation data.
// create services
var services = new ServiceCollection();
// add and register
services.UseIpGeolocation(settings: new IpGeolocationSettings { CacheType = CacheType.MemoryAndFile });
// build service provider
var serviceProvider = services.BuildServiceProvider();
// get service and call method to get geolocation
var ipGeolocation = await serviceProvider.GetRequiredService<IIpGeolocationService>().GetIpGeolocationAsync("8.8.8.8");
// print geolocation data
Console.WriteLine(ipGeolocation.CountryName); // United States
// dispose service provider to release resources
serviceProvider.Dispose();
Configuration
The library allows you to configure the cache type and the cache expiration time. You can do this by creating an instance of the IpGeolocationSettings
class and passing
it to the UseIpGeolocation
method.
services.UseIpGeolocation(settings: services.UseIpGeolocation(settings: new IpGeolocationSettings
{ CacheType = CacheType.MemoryAndFile, CacheExpirationType = CacheExpirationType.Minutes, CacheExpiration = 60 });
Cache types
The library supports two cache types:
Memory
- cache data in memoryMemoryAndFile
- cache data in memory and file
Cache expiration types
The library supports two cache expiration types:
Seconds
- cache expiration time in secondsMinutes
- cache expiration time in minutesHours
- cache expiration time in hoursDays
- cache expiration time in daysNever
- cache never expires
Cache
More information about the cache can be found in the CacheDrive library.
Usage with configuration file
The library allows you to use configuration files to configure the library. You can do this by adding the configuration section to the appsettings.json
file.
{
"IpGeolocationSettings": {
"BaseAddress": "https://ipapi.co/",
"CacheEnabled": true,
"CacheFolderName": "cache",
"CacheExpirationType": "Minutes",
"CacheExpiration": 60,
"CacheType": "MemoryAndFile",
"InitializeOnStartup": true,
"FlushOnExit": true,
"HashKeySalt": "123s123",
"ApiKey": ""
}
}
- BaseAddress - Base address of the ipapi.co API
- CacheEnabled - Determines whether cache is enabled. Default value is true.
- CacheFolderName - Cache folder name. Default value is "cache".
- CacheExpirationType - In what units do we specify cache expiration. Default value is Minutes.
- CacheExpiration - After what time the objects in the cache will expire. Based on CacheExpirationType. Default value is 60.
- CacheType - Method of storing the cache. Memory - only in memory. MemoryAndFile - In memory while the application is running and in files after the application is closed. Default value is Memory.
- InitializeOnStartup - Determines whether the cache should be initialized at startup. Default value is true.
- FlushOnExit - Determines whether the cache should be flushed to a files when the application is closed. Default value is true.
- HashKeySalt - Salt, which will be added to the key hash. Default value is an empty string, which means that adding salt is disabled.
- ApiKey - API key for the paid version of the ipapi.co API. Default value is an empty string, which means that the free version of the ipapi.co API will be used.
Then you can use the UseIpGeolocation
method to add and register the library with the configuration.
// create services
var services = new ServiceCollection();
// build config
IConfiguration configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.AddJsonFile("appsettings.dev.json", optional: true, reloadOnChange: true)
.AddEnvironmentVariables()
.Build();
// add and register services:
services.UseIpGeolocation(configuration);
// build service provider
var serviceProvider = services.BuildServiceProvider();
// get service and call method to get geolocation
var ipGeolocation = await serviceProvider.GetRequiredService<IIpGeolocationService>().GetIpGeolocationAsync("8.8.8.8");
// print geolocation data
Console.WriteLine(ipGeolocation.CountryName); // United States
// dispose service provider to release resources
serviceProvider.Dispose();
How to use paid version of the ipapi.co API
If you want to use the paid version of the ipapi.co API, you need to provide the API key in the configuration file or in the IpGeolocationSettings
class.
{
"IpGeolocationSettings": {
"ApiKey": "your_api_key"
}
}
If you leave the ApiKey
property empty or do not provide it, the library will use the free version of the ipapi.co API.
Code Examples
- IpGeolocation.ConsoleApp - console application with example use of the IpGeolocation library https://github.com/kubagdynia/IpGeolocation/tree/main/IpGeolocation.ConsoleApp
- IpGeolocation.ConsoleApp.WithoutConfig - console application with example use of the IpGeolocation library without configuration https://github.com/kubagdynia/IpGeolocation/tree/main/IpGeolocation.ConsoleApp.WithoutConfig
License
The library is available under the MIT license.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net7.0
- CacheDrive (>= 0.2.4)
- Microsoft.Extensions.Caching.Memory (>= 8.0.1)
- Microsoft.Extensions.Configuration (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection (>= 8.0.1)
- Microsoft.Extensions.Http (>= 8.0.1)
- Microsoft.Extensions.Http.Polly (>= 8.0.10)
- Microsoft.Extensions.Logging (>= 8.0.1)
- Microsoft.Extensions.Options (>= 8.0.2)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 8.0.0)
- Polly (>= 8.4.2)
-
net8.0
- CacheDrive (>= 0.2.4)
- Microsoft.Extensions.Caching.Memory (>= 8.0.1)
- Microsoft.Extensions.Configuration (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection (>= 8.0.1)
- Microsoft.Extensions.Http (>= 8.0.1)
- Microsoft.Extensions.Http.Polly (>= 8.0.10)
- Microsoft.Extensions.Logging (>= 8.0.1)
- Microsoft.Extensions.Options (>= 8.0.2)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 8.0.0)
- Polly (>= 8.4.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
The issue with error handling from the external API has been resolved.