IPGeolocation.io .NET SDK
Overview
Official .NET SDK for the IPGeolocation.io IP Geolocation API.
Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, time zone, network, hostname, abuse, user-agent, and security data from one API.
- .NET Standard 2.1 package
- Async client built on
HttpClient - Typed responses plus raw JSON and XML methods
Install
dotnet add package IPGeoLocation.IPGeolocationInstall-Package IPGeoLocation.IPGeolocation<PackageReference Include="IPGeoLocation.IPGeolocation" Version="3.0.1" />- NuGet package:
IPGeoLocation.IPGeolocation - Package page: https://www.nuget.org/packages/IPGeoLocation.IPGeolocation
- GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-dotnet-sdk
Quick Start
using System;
using IPGeolocation;
var apiKey = Environment.GetEnvironmentVariable("IPGEO_API_KEY")
?? throw new InvalidOperationException("Set IPGEO_API_KEY first.");
using var client = new IpGeolocationClient(new IpGeolocationClientConfig(apiKey: apiKey));
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(ip: "8.8.8.8"));
Console.WriteLine(response.Data.Ip); // 8.8.8.8
Console.WriteLine(response.Data.Location?.CountryName); // United States
Console.WriteLine(response.Data.Location?.City);
Console.WriteLine(response.Data.TimeZone?.Name);
Console.WriteLine(response.Metadata.CreditsCharged ?? 0);Use LookupIpGeolocationRequest and BulkLookupIpGeolocationRequest when you want request validation before the call is sent.
At a Glance
| Item | Value |
|---|---|
| Package | IPGeoLocation.IPGeolocation |
| Namespace | IPGeolocation |
| Supported Endpoints | /v3/ipgeo, /v3/ipgeo-bulk |
| Supported Inputs | IPv4, IPv6, domain |
| Main Data Returned | Geolocation, company, ASN, time zone, network, hostname, abuse, user-agent, currency, security |
| Authentication | API key, request-origin auth for /v3/ipgeo only |
| Response Formats | Structured JSON, raw JSON, raw XML |
| Bulk Limit | Up to 50,000 IPs or domains per request |
| Transport | HttpClient |
Get Your API Key
Create an IPGeolocation.io account and copy an API key from your dashboard.
- Sign up: https://app.ipgeolocation.io/signup
- Verify your email if prompted
- Sign in: https://app.ipgeolocation.io/login
- Open your dashboard: https://app.ipgeolocation.io/dashboard
- Copy an API key from the
API Keyssection
For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.
Authentication
1. API Key
using IPGeolocation;
using var client = new IpGeolocationClient(
new IpGeolocationClientConfig(apiKey: Environment.GetEnvironmentVariable("IPGEO_API_KEY")));2. Request-Origin Auth
using IPGeolocation;
using var client = new IpGeolocationClient(
new IpGeolocationClientConfig(requestOrigin: "https://app.example.com"));requestOrigin must be an absolute http or https origin with no path, query string, fragment, or userinfo.
Plan Behavior
Feature availability depends on your plan and request parameters.
| Capability | Free | Paid |
|---|---|---|
| Single IPv4 and IPv6 lookup | Supported | Supported |
| Domain lookup | Not supported | Supported |
| Bulk lookup | Not supported | Supported |
Non-English lang | Not supported | Supported |
| Request-origin auth | Not supported | Supported for /v3/ipgeo only |
Optional modules via include | Not supported | Supported |
include: ["*"] | Base response only | All plan-available modules |
Paid plans still need the include parameter for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.
Client Configuration
| Field | Type | Default | Notes |
|---|---|---|---|
apiKey | string? | unset | Required for bulk lookup. Optional for single lookup if requestOrigin is set. |
requestOrigin | string? | unset | Must be an absolute http or https origin. |
baseUrl | string | https://api.ipgeolocation.io | Override the API base URL. |
connectTimeout | TimeSpan | 10 seconds | Time to connect and receive response headers. |
readTimeout | TimeSpan | 30 seconds | Time to wait for the next part of the response. |
The client constructor accepts an IpGeolocationClientConfig. Both timeouts must be greater than zero.
Available Methods
| Method | Returns | Notes |
|---|---|---|
LookupIpGeolocationAsync(request = null, | Task<ApiResponse<IpGeolocationResponse>> | Single lookup. Typed JSON response. |
LookupIpGeolocationRawAsync(request = null, | Task<ApiResponse<string>> | Single lookup. Raw JSON or XML string. |
BulkLookupIpGeolocationAsync(request, | Task<ApiResponse<IReadOnlyList<BulkLookupResult>>> | Bulk lookup. Typed JSON response. |
BulkLookupIpGeolocationRawAsync(request, | Task<ApiResponse<string>> | Bulk lookup. Raw JSON or XML string. |
Dispose() | void | Closes the client and releases its transport. |
Request Options
| Field | Applies To | Notes |
|---|---|---|
ip | Single lookup | IPv4, IPv6, or domain. Omit it for caller IP lookup. |
ips | Bulk lookup | Collection of 1 to 50,000 IPs or domains. |
lang | Single and bulk | One of en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar. |
include | Single and bulk | Collection of module names such as security, abuse, user_agent, hostname, liveHostname, hostnameFallbackLive, geo_accuracy, dma_code, or *. |
fields | Single and bulk | Collection of field paths to keep, for example location.country_name or security.threat_score. |
excludes | Single and bulk | Collection of field paths to remove from the response. |
userAgent | Single and bulk | Overrides the outbound User-Agent header. |
headers | Single and bulk | Extra request headers as IReadOnlyDictionary<string,. |
output | Single and bulk | ResponseFormat.Json or ResponseFormat.Xml. Typed methods require JSON. |
Examples
The examples below assume you already have a configured client in scope:
using System;
using System.Linq;
using IPGeolocation;
var apiKey = Environment.GetEnvironmentVariable("IPGEO_API_KEY")
?? throw new InvalidOperationException("Set IPGEO_API_KEY first.");
using var client = new IpGeolocationClient(new IpGeolocationClientConfig(apiKey: apiKey));1. Caller IP
Omit ip to look up the public IP of the machine making the request.
var response = await client.LookupIpGeolocationAsync();
Console.WriteLine(response.Data.Ip);2. Domain Lookup
Domain lookup is a paid-plan feature.
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(ip: "ipgeolocation.io"));
Console.WriteLine(response.Data.Ip);
Console.WriteLine(response.Data.Domain); // ipgeolocation.io
Console.WriteLine(response.Data.Location?.CountryName);3. Security and Abuse
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(
ip: "9.9.9.9",
include: new[] { "security", "abuse" }));
Console.WriteLine(response.Data.Security?.ThreatScore);
Console.WriteLine(response.Data.Abuse?.Emails?.FirstOrDefault());4. User-Agent Parsing
To parse a visitor user-agent string, pass include: ["user_agent"] and send the visitor string in the request User-Agent header.
using System.Collections.Generic;
const string visitorUa =
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9";
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(
ip: "115.240.90.163",
include: new[] { "user_agent" },
headers: new Dictionary<string, string> { ["User-Agent"] = visitorUa }));
Console.WriteLine(response.Data.UserAgent?.Name);
Console.WriteLine(response.Data.UserAgent?.OperatingSystem?.Name);5. Filtered Response
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(
ip: "8.8.8.8",
include: new[] { "security" },
fields: new[] { "location.country_name", "security.threat_score", "security.is_vpn" },
excludes: new[] { "currency" }));
Console.WriteLine(response.Data.Location?.CountryName);
Console.WriteLine(response.Data.Security?.ThreatScore);
Console.WriteLine(response.Data.Security?.IsVpn);
Console.WriteLine(response.Data.Currency is null); // True6. Raw XML
var response = await client.LookupIpGeolocationRawAsync(
new LookupIpGeolocationRequest(
ip: "8.8.8.8",
output: ResponseFormat.Xml));
Console.WriteLine(response.Data);7. Bulk Lookup
var response = await client.BulkLookupIpGeolocationAsync(
new BulkLookupIpGeolocationRequest(new[] { "8.8.8.8", "1.1.1.1" }));
foreach (var result in response.Data)
{
if (result is BulkLookupSuccess success)
{
Console.WriteLine(success.Data.Ip);
continue;
}
if (result is BulkLookupError error)
{
Console.WriteLine(error.Error.Message);
}
}8. Raw Bulk JSON
var response = await client.BulkLookupIpGeolocationRawAsync(
new BulkLookupIpGeolocationRequest(new[] { "8.8.8.8", "1.1.1.1" }));
Console.WriteLine(response.Data);Response Metadata
Every method returns ApiResponse<T>, where:
Datacontains the typed object or raw response stringMetadatacontains response details such as:CreditsChargedSuccessfulRecordsStatusCodeDurationMsRawHeaders
Example:
Console.WriteLine(response.Metadata.StatusCode);
Console.WriteLine(response.Metadata.DurationMs);
Console.WriteLine(response.Metadata.FirstHeaderValue("content-type"));Errors
The SDK throws typed exceptions instead of returning error objects for failed HTTP responses. SDK error messages replace your configured API key with [REDACTED]. SDK error types and HTTP status codes stay the same. Some technical error details may be shortened to keep the key hidden.
| Exception | When It Happens |
|---|---|
ValidationException | Invalid config, invalid request values, or typed XML request |
RequestTimeoutException | Connect timeout or read timeout |
TransportException | Network or transport failure |
SerializationException | Request or response serialization failure |
ApiException | API returned a non-2xx response |
ApiException has status-specific subclasses:
BadRequestExceptionUnauthorizedExceptionForbiddenExceptionNotFoundExceptionMethodNotAllowedExceptionContentTooLargeExceptionUnsupportedMediaTypeExceptionLockedExceptionTooManyRequestsExceptionCustomStatus499ExceptionInternalServerErrorException
Example:
try
{
var response = await client.LookupIpGeolocationAsync(
new LookupIpGeolocationRequest(output: ResponseFormat.Xml));
}
catch (ValidationException error)
{
Console.WriteLine(error.Message);
}
catch (ApiException error)
{
Console.WriteLine((int)error.StatusCode);
Console.WriteLine(error.Message);
}Troubleshooting
- Bulk lookup always requires
apiKey.requestOriginis not enough. - Typed methods only support JSON. Use the raw methods for XML.
- If you need security, abuse, user-agent, or hostname data, include those modules explicitly.
fieldsandexcludesfilter the response. They do not unlock paid data.requestOriginmust be an origin only. Do not include a path, query string, fragment, or userinfo.
Frequently Asked Questions
LookupIpGeolocationRawAsync or BulkLookupIpGeolocationRawAsync for XML.include, for example security, abuse, hostname, or user_agent.Links
- Homepage: https://ipgeolocation.io
- IP Geolocation API product page: https://ipgeolocation.io/ip-location-api.html
- Documentation: https://ipgeolocation.io/documentation/ip-location-api.html
- NuGet package: https://www.nuget.org/packages/IPGeoLocation.IPGeolocation
- GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-dotnet-sdk