{"id":15412261,"url":"https://github.com/robthree/ip2country","last_synced_at":"2025-04-19T03:19:23.438Z","repository":{"id":41512139,"uuid":"122321319","full_name":"RobThree/IP2Country","owner":"RobThree","description":"Ip to country mapping","archived":false,"fork":false,"pushed_at":"2022-03-17T10:47:09.000Z","size":160,"stargazers_count":50,"open_issues_count":2,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-16T03:55:35.189Z","etag":null,"topics":["geolocation","ip-country","ip-geo","ip-geolocation","ip-lookup","ip-to-country","ip2country","ip2location","ipgeolocation","iptocountry"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobThree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["RobThree"],"custom":["https://paypal.me/robiii"]}},"created_at":"2018-02-21T10:21:10.000Z","updated_at":"2024-12-20T08:22:11.000Z","dependencies_parsed_at":"2022-09-08T12:24:48.952Z","dependency_job_id":null,"html_url":"https://github.com/RobThree/IP2Country","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThree%2FIP2Country","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThree%2FIP2Country/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThree%2FIP2Country/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThree%2FIP2Country/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobThree","download_url":"https://codeload.github.com/RobThree/IP2Country/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249598382,"owners_count":21297464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","ip-country","ip-geo","ip-geolocation","ip-lookup","ip-to-country","ip2country","ip2location","ipgeolocation","iptocountry"],"created_at":"2024-10-01T16:52:00.230Z","updated_at":"2025-04-19T03:19:23.390Z","avatar_url":"https://github.com/RobThree.png","language":"C#","readme":"# ![Logo](https://raw.githubusercontent.com/RobThree/IP2Country/master/icons/icon.png) IP2Country\nLibrary to map IP addresses (both IPv4 and IPv6) to a country, available as [NuGet package](https://www.nuget.org/packages/IP-2-Country/). The accuracy depends on the data provider; a lot of providers are supported 'out of the box':\n\n* All registries ([RIPE](https://www.ripe.net/), [APNIC](https://www.apnic.net/), [ARIN](https://www.arin.net/), [LACNIC](http://www.lacnic.net/) and [AFRINIC](https://www.afrinic.net/)) ([NuGet](https://www.nuget.org/packages/IP-2-Country.Registries/))\n* [DB-IP](https://db-ip.com/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.DbIp/))\n* [IP2IQ](http://www.ip2iq.com/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.IP2IQ/))\n* [IP2Location Lite](https://lite.ip2location.com/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.IP2Location.Lite/))\n* [IPToASN](https://iptoasn.com/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.IpToAsn/))\n* [Ludost](https://ip.ludost.net/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.Ludost/))\n* [Markus Go's ip-countryside](https://github.com/Markus-Go/ip-countryside/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.MarkusGo/))\n* [MaxMind](https://www.maxmind.com) ([NuGet](https://www.nuget.org/packages/IP-2-Country.MaxMind/))\n* [WebNet77](http://software77.net/geo-ip/) ([NuGet](https://www.nuget.org/packages/IP-2-Country.WebNet77/))\n\nAlso available is a caching `IIP2CountryResolver` in the form of a [IP2Country.Caching NuGet package](https://www.nuget.org/packages/IP2Country.Caching).\n\nThis library provides an easy to implement interface (`IIP2CountryDataSource`) to provide your own data to the `IP2CountryResolver`. This library only aims for 'country level resolution'; city, ISP etc. information _can_ be returned (when provided) but is not the goal of this library. All data is stored in entities / models derived from `IIPRangeCountry` which, at the very minimum, must provide a start- and end IP address (IPv4 and/or IPv6, supported completely transparently) and country (_usually_ an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, but may contain other data depending on the data source).\n\n## Usage\n\nIn general, you'll want to use one of the above mentioned datasources. You can combine them but it's recommended to use a single one. Install the desired NuGet package (e.g. `IP-2-Country.MaxMind`) which will also pull in the base package (`IP-2-Country`) and the generic CSV parser (`IP-2-Country.DataSources.CSVFile`). Download the datafiles (example code is provided in the DemoApp in this repository) and create an IP2CountryResolver object:\n\n```c#\nvar resolver = new IP2CountryResolver(\n    // Country level file, using MaxMind as an example\n    new MaxMindGeoLiteFileSource(@\"D:\\files\\GeoLite2-Country-CSV_20190305.zip\")\n);\n```\n\nAnd you're done! Now you can resolve IP addresses:\n\n```c#\nvar result = resolver.Resolve(\"172.217.17.110\");\nConsole.WriteLine(\"Country: \" + result?.Country);\n```\n\nDepending on the datasource some more information _may_ be returned (for example: the `IP-2-Country.Registries` package returns the `Registry`, `Date`, `Status` and even some `Extensions` when available). You may need to cast to the returned type in case you need more than the `IIPRangeCountry` interface provides:\n\n```c#\nvar result = (RegistryIPRangeCountry)resolver.Resolve(\"172.217.17.110\");\n```\n\nThe following overloads / convenience-methods are available:\n\n```c#\n// IIP2CountryResolver\nIIPRangeCountry Resolve(string ip);\nIIPRangeCountry Resolve(IPAddress ip);\n\n// IIP2CountryBatchResolver\nIIPRangeCountry[] Resolve(string[] ips);\nIIPRangeCountry[] Resolve(IPAddress[] ips);\nIIPRangeCountry[] Resolve(IEnumerable\u003cstring\u003e ips);\nIIPRangeCountry[] Resolve(IEnumerable\u003cIPAddress\u003e ips);\nIDictionary\u003cstring, IIPRangeCountry\u003e ResolveAsDictionary(string[] ips);\nIDictionary\u003cIPAddress, IIPRangeCountry\u003e ResolveAsDictionary(IPAddress[] ips);\nIDictionary\u003cstring, IIPRangeCountry\u003e ResolveAsDictionary(IEnumerable\u003cstring\u003e ips);\nIDictionary\u003cIPAddress, IIPRangeCountry\u003e ResolveAsDictionary(IEnumerable\u003cIPAddress\u003e ips);\n````\n\nTo resolve more than one IP address you can use the `IP2CountryBatchResolver`:\n\n```c#\nvar resolver = new IP2CountryBatchResolver(new IP2CountryResolver(\n    new DbIpCSVFileSource(@\"D:\\files\\dbip-country-lite-2019-10.csv.gz\")\t// Use ANY datasource you want\n));\n\nvar results = resolve.Resolve(new[] { \"172.217.17.110\", \"172.217.17.111\", \"172.217.17.112\" });\n```\n\nTo use caching, use the `CachingIP2CountryResolver` from the `IP2Country.Caching` package:\n\n```c#\nvar memcache = new MemoryCache(new MemoryCacheOptions { /* ... */ });\nvar resolver = new CachingIP2CountryResolver(new IP2CountryResolver(\n    new LudostCSVFileSource(@\"D:\\files\\country.db.gz\")\t// Use ANY datasource you want\n\tmemcache,               // IMemoryCache instance (in this case a MemoryCache)\n\tTimeSpan.FromHours(1)\t// TTL for cached entries\n));\n\nvar result = resolver.Resolve(\"172.217.17.110\");\n```\n\nAnd, ofcourse, even the `CachingIP2CountryResolver` can be used for batch lookups:\n\n```c#\nvar memcache = new MemoryCache(new MemoryCacheOptions { /* ... */ });\nvar resolver = new IP2CountryBatchResolver(new CachingIP2CountryResolver(new IP2CountryResolver(\n    new WebNet77IPv4CSVFileSource(@\"D:\\files\\IpToCountry.csv.gz\")\t// Use ANY datasource you want\n\tmemcache,\t\t// IMemoryCache instance (in this case a MemoryCache)\n\tTimeSpan.FromHours(1)\t// TTL for cached entries\n)));\n\nvar results = resolve.Resolve(new[] { \"172.217.17.110\", \"172.217.17.111\", \"172.217.17.112\" });\n```\n\n## IIP2CountryBatchResolver and caching\n\nAn `IP2CountryBatchResolver` class is provided to help in resolving many IP's at once. This object takes an `IIP2CountryResolver` for it's constructor parameter and is nothing more than a simple wrapper implementing the 'batch'-methods.\n\nThe `IP2Country.Caching` package provides a resolver that takes an `IMemoryCache` to provide a caching mechanism and a `TimeSpan` to specify how long entries should be cached. Unless you have to resolve a lot of duplicate IP's, the caching probably doesn't add very much value.\n\n## Datasources\n\nBesides the provided datasources it's very simple to implement your own datasource; all you need to do is implement a single method (`IEnumerable\u003cIIPRangeCountry\u003e Read()`) from a single interface (`IIP2CountryDataSource`). It's up to you whether you want to use a CSV file, binary file, database, Excel file or whatever other method of storage you can imagine. As long as you can provide IP ranges (as start/end pairs) and country data (as string) as an IEnumerable source you're done. This repository has lots of examples of CSV datasources but it's perfectly fine to build and provide your own datasource.\n\n### A word on the actual data\n\nThe provided datasources are nothing but simple \"CSV file readers\". It's up to you to download the actual data files (and cache them for later use). The DemoApp contains an example of downloading files into a temp directory and caching them. You can implement your own download/cache mechanism as you see fit for your project. As long as you can provide a datasource that implements the [`IIP2CountryDataSource`](IP2Country/Datasources/IIP2CountryDataSource.cs) interface this library doesn't care about the rest.\n\nMore on actual, compatible, databases can be found [in the wiki](../../wiki/IP-to-country-databases)\n\n## Accuracy\n\nThe accuracy depends entirely on the accuracy of the datasource. This library has no built-in data whatsoever. You _may_ also want to ensure your datasource doesn't provide ranges to the `IP2CountryResolver` that overlap. It's up to you / the datasource to ensure the data is as accurate as possible (and as up-to-date as possible).\n\n## Benchmarks / performance:\n\nOn an [Intel Xeon E3-1225 v3](https://ark.intel.com/products/75461/Intel-Xeon-Processor-E3-1225-v3-8M-Cache-3_20-GHz) CPU it's perfectly possible to achieve over **2,000,000 lookups per second** (yes, that is over 2 million on an CPU from 2013!). Obviously results will vary depending on the size of the dataset, the usage, the CPU and other factors.\n\nNote that when an instance of an `IP2CountryResolver` is created it will load **all** the data from the datasource into memory. Naturally this is a costly, though one-time, operation. As long as the `IP2CountryResolver` object is kept alive you can (re)use it to resolve IP addresses. We recommend creating an instance once and keeping it around as long as possible. Create a new instance and swap it out with the old one if there is new data available from the datasource.\n\n## Icon\nSource: [ShareIcon.Net](https://www.shareicon.net/internet-marketing-geo-geo-location-geomarketing-ip-address-isp-address-target-888208)\nAuthor: [Ayesha Nasir](https://www.shareicon.net/author/ayesha-nasir)\nLicense: [Creative Commons (Attribution 3.0 Unported)](https://creativecommons.org/licenses/by/3.0/)\n\u003chr\u003e\n\n[![Build status](https://ci.appveyor.com/api/projects/status/bs1l4mjdnlusv4n5?svg=true)](https://ci.appveyor.com/project/RobIII/ip2country) \u003ca href=\"https://www.nuget.org/packages/IP-2-Country/\"\u003e\u003cimg src=\"http://img.shields.io/nuget/v/IP-2-Country.svg?style=flat-square\" alt=\"NuGet version\" height=\"18\"\u003e\u003c/a\u003e\n","funding_links":["https://github.com/sponsors/RobThree","https://paypal.me/robiii"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobthree%2Fip2country","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobthree%2Fip2country","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobthree%2Fip2country/lists"}