IPGeolocation .NET SDK

Overview

Official .NET SDK for the IPGeolocation.io IP Location API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, 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.IPGeolocation

Install-Package IPGeoLocation.IPGeolocation

<PackageReference Include="IPGeoLocation.IPGeolocation" Version="3.0.0" />

• 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

Get Your API Key

Create an IPGeolocation account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

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.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

The client constructor accepts an IpGeolocationClientConfig . Timeouts are validated before the request is sent.

Available Methods

Request Options

Examples

The examples below assume you already have a configured client in scope:

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();
Console.WriteLine(response.Data.Ip);

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);

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?[0]);

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);

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); // True

var response = await client.LookupIpGeolocationRawAsync(
    new LookupIpGeolocationRequest(
        ip: "8.8.8.8",
        output: ResponseFormat.Xml));

Console.WriteLine(response.Data);

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);
    }
}

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:

• Data contains the typed object or raw response string
• Metadata contains response details such as:
  • CreditsCharged
  • SuccessfulRecords
  • StatusCode
  • DurationMs
  • RawHeaders

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.

ApiException has status-specific subclasses:

• BadRequestException
• UnauthorizedException
• ForbiddenException
• NotFoundException
• MethodNotAllowedException
• ContentTooLargeException
• UnsupportedMediaTypeException
• LockedException
• TooManyRequestsException
• CustomStatus499Exception
• InternalServerErrorException

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 . requestOrigin is 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.
• fields and excludes filter the response. They do not unlock paid data.
• requestOrigin must be an origin only. Do not include a path, query string, fragment, or userinfo.

Frequently Asked Questions

Only for single lookup with paid-plan request-origin auth. Bulk lookup always requires an API key.

No. Typed methods only support JSON. Use LookupIpGeolocationRawAsync or BulkLookupIpGeolocationRawAsync for XML.

No. Domain lookup is a paid-plan feature.

Pass the right modules in include , for example security , abuse , hostname , or user_agent .

Links

• Homepage: https://ipgeolocation.io
• IP Location 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