
IP2Location™ IP Geolocation Web Service
IP2Location™ IP Geolocation web service is a REST API providing a service to do a reverse IP location lookup for ISO3166 country code, region or state, city, latitude and longitude, ZIP/Postal code, time zone, Internet Service Provider (ISP) or company name, domain name, net speed, area code, weather station code, weather station name, mobile country code (MCC), mobile network code (MNC) and carrier brand, elevation, and usage type. To search, submit a query string and a set of parameters to the IP2Location™ REST API service and you will get the IP location lookup within seconds. Search results are derived from the IP2Location™ index of over 4 billion unique IP addresses.
IPv4 and IPv6 supported.
All successful HTTP or HTTPS requests will return a response code of 200, together with the lookup information. Error code will be returned if an error occurred.
Each unit of package purchase entitles you to 100,000 query credits. If you need more credits, please add multiple units during checkout. Total credits will be the number of units purchased multiplied by 100,000. However, please note that only one unique API key will be given for each user account, even if multiple units are purchased. If you need a different API key, you should sign up using a different email account.
IP2Location™ web service is a RESTful API call for geolocation lookup. The REST API supports both HTTP GET or HTTPS GET.
- No database to download, to install or to upgrade in the server-side
- Supports 24 different types of package queries with a different granularity of data.
- Supports additional information (optional), such as Olson time zone, translations and so on.
- Supports HTTP or HTTPS queries up to 100,000 times or 1 year (whichever comes first)
You can try out our web service by using the demo key. The demo query limit is 20 per day.
Example for querying an IPv4 address:
https://api.ip2location.com/v2/?ip=142.113.220.31&addon=continent&lang=zh-cn&key=demo
Example for querying an IPv6 address:
https://api.ip2location.com/v2/?ip=2607:f8b0:4001:c02::93&addon=continent&lang=zh-cn&key=demo
Example to check remaining credits:
https://api.ip2location.com/v2/?key=demo&check=1
Need more credits? You can sign up for a free trial key that will entitle you to a one time 5,000 free credits to evaluate our services.
The REST API calling syntax. Please see the table below for description of each parameter.
https://api.ip2location.com/v2/?ip={IP_ADDRESS}&key={YOUR_API_KEY}&package={WS1|WS2|WS3|...|WS24}&addon={continent,country,region,city,geotargeting,country_groupings,time_zone_info}
Name | Description |
---|---|
key | (required) API key. |
ip | (required) IP address (IPv4 or IPv6) for reverse IP location lookup purposes. If not present, the server IP address will be used for the location lookup. |
package |
(required) Web service package of different granularity of return information. Valid value: WS1 | WS2 | WS3 | WS4 | WS5 | WS6 | WS7 | WS8 | WS9 | WS10 | WS11 | WS12 | WS13 | WS14 | WS15 | WS16 | WS17 | WS18 | WS19 | WS20 | WS21 | WS22 | WS23 | WS24 Please refer to the below pricing table for the information returned. |
format |
(optional) Format of the response message. Valid value: json | xml If unspecified, json format will be used for the response message. |
addon |
(optional) Extra information in addition to the above-selected package. Valid value: continent, country, region, city, geotargeting, country_groupings, time_zone_info Please refer to the below pricing table for the information returned. |
lang |
(optional) Translation information. The translation is only applicable for continent, country, region and city name for the addon package. Valid value: ar | cs | da | de | en | es | et | fi | fr | ga | it | ja | ko | ms | nl | pt | ru | sv | tr | vi | zh-cn | zh-tw You can only specify one language value for the returns. |
Package Response Fields
Field | Description |
---|---|
country_code | Two-character country code based on ISO 3166. |
country_name | Country name based on ISO 3166. |
region_name | Region or state name. |
city_name | City name. |
latitude | City latitude. Defaults to capital city latitude if city is unknown. |
longitude | City longitude. Defaults to capital city longitude if city is unknown. |
zip_code | ZIP/Postal code (170 countries supported). |
time_zone | UTC time zone (with DST supported). |
isp | Internet Service Provider or company's name. |
domain | Internet domain name associated with IP address range. |
net_speed | Internet connection type. DIAL = dial-up, DSL = broadband/cable/fiber/mobile, COMP = company/T1 |
idd_code | The IDD prefix to call the city from another country. |
area_code | A varying length number assigned to geographic areas for calls between cities (221 countries supported). |
weather_station_code | The special code to identify the nearest weather observation station. |
weather_station_name | The name of the nearest weather observation station. |
mcc | Mobile Country Codes (MCC) as defined in ITU E.212 for use in identifying mobile stations in wireless telephone networks, particularly GSM and UMTS networks. |
mnc | Mobile Network Code (MNC) is used in combination with a Mobile Country Code (MCC) to uniquely identify a mobile phone operator or carrier. |
mobile_brand | Commercial brand associated with the mobile carrier. You may click here to view the coverage report. |
elevation | Average height of city above sea level in meters (m). |
usage_type | Usage type classification of ISP or company (COM) Commercial (ORG) Organization (GOV) Government (MIL) Military (EDU) University/College/School (LIB) Library (CDN) Content Delivery Network (ISP) Fixed Line ISP (MOB) Mobile ISP (DCH) Data Center/Web Hosting/Transit (SES) Search Engine Spider (RSV) Reserved |
credits_consumed | Credits needed to perform geolocation lookup. |
Add-On Response Fields
Continent
Field | Description |
---|---|
(addon: continent) code |
Two-character continent code. |
(addon: continent) name |
Continent name. |
(addon: continent) hemisphere |
The hemisphere of where the country located. The data in array format with first item indicates (north/south) hemisphere and second item indicates (east/west) hemisphere information. |
(addon: continent) translations |
Translation data based on the given lang code. |
Country
Field | Description |
---|---|
(addon: country) name |
Country name based on ISO 3166. |
(addon: country) alpha3_code |
Three-character country code based on ISO 3166. |
(addon: country) numeric_code |
Three-character country numeric code based on ISO 3166. |
(addon: country) flag |
URL of the country flag image. |
(addon: country) capital |
Capital of the country. |
(addon: country) total_area |
Total area in km2. |
(addon: country) population |
Population of the country. |
(addon: country) currency -> code |
Currency code based on ISO 4217. |
(addon: country) currency -> name |
Currency name. |
(addon: country) currency -> symbol |
Currency symbol. |
(addon: country) language -> code |
Language code based on ISO 639. |
(addon: country) language -> name |
Language name. |
(addon: country) idd_code |
The IDD prefix to call the city from another country. |
(addon: country) tld |
Country-Code Top-Level Domain. |
(addon: country) translations |
Translation data based on the given lang code. |
Region
Field | Description |
---|---|
(addon: region) name |
Region or state name. |
(addon: region) code |
ISO3166-2 code. |
(addon: region) translation |
Translation data based on the given lang code. |
City
Field | Description |
---|---|
(addon: city) name |
City name. |
(addon: city) translation |
Translation data based on the given lang code. |
Geotargeting
Field | Description |
---|---|
(addon: geotargeting) metro |
Metro code based on zip/postal code. |
Country Grouping
Field | Description |
---|---|
(addon: country_groupings) acronym |
Acronym of the country grouping. |
(addon: country_groupings) name |
Name of the country grouping. |
Time Zone
Field | Description |
---|---|
(addon: time_zone_info) olson |
Time zone in olson format. |
(addon: time_zone_info) current_time |
Current time in ISO 8601 format. |
(addon: time_zone_info) gmt_offset |
GMT offset value in seconds. |
(addon: time_zone_info) is_dst |
Indicate if the time zone value is in DST. |
(addon: time_zone_info) sunrise |
Time of sunrise. (hh:mm format in local time, i.e, 07:47) |
(addon: time_zone_info) sunset |
Time of sunset. (hh:mm format in local time, i.e 19:50) |
You can pick an appropriate package from the 24 packages below to start adding IP location lookup web service to your solution. Each package returns a different set of IP address information with different amounts of credits deducted for each query.
Package | Information Returned | Credit |
---|---|---|
WS1 |
Country Code | 1 credit |
WS2 |
Country, ISP | 2 credits |
WS3 |
Country, Region, City | 2 credits |
WS4 |
Country, Region, City, ISP | 3 credits |
WS5 |
Country, Region, City, Latitude, Longitude | 3 credits |
WS6 |
Country, Region, City, Latitude, Longitude, ISP | 4 credits |
WS7 |
Country, Region, City, ISP, Domain | 4 credits |
WS8 |
Country, Region, City, Latitude, Longitude, ISP, Domain | 5 credits |
WS9 |
Country, Region, City, Latitude, Longitude, ZIP Code | 4 credits |
WS10 |
Country, Region, City, Latitude, Longitude, ZIP Code, ISP, Domain | 6 credits |
WS11 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone | 5 credits |
WS12 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain | 7 credits |
WS13 |
Country, Region, City, Latitude, Longitude, Time Zone, Net Speed | 5 credits |
WS14 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed | 8 credits |
WS15 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, Area Code | 7 credits |
WS16 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed, Area Code | 10 credits |
WS17 |
Country, Region, City, Latitude, Longitude, Time Zone, Net Speed, Weather | 6 credits |
WS18 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed, Area Code, Weather | 11 credits |
WS19 |
Country, Region, City, Latitude, Longitude, ISP, Domain, Mobile | 8 credits |
WS20 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed, Area Code, Weather, Mobile | 14 credits |
WS21 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, Area Code, Elevation | 8 credits |
WS22 |
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed, Area Code, Weather, Mobile, Elevation | 15 credits |
WS23 |
Country, Region, City, Latitude, Longitude, ISP, Domain, Mobile, UsageType | 11 credits |
![]()
WS24
|
Country, Region, City, Latitude, Longitude, ZIP Code, Time Zone, ISP, Domain, Net Speed, Area Code, Weather, Mobile, Elevation, UsageType | 18 credits |
Add On | Information Returned | Credit |
---|---|---|
continent | Continent details with multilingual supports. | 1 credit |
country | Country information with multilingual supports. | 2 credits |
region | Region names with multilingual supports. Required WS3 and above. | 2 credits |
city | City names with multilingual supports. Required WS3 and above. | 2 credits |
geotargeting | Metro code for supported area. Required the package that has zip code data, such as WS9. | 2 credits |
country_groupings | Country Grouping Terminology. | 2 credits |
time_zone_info | Local time in real time. Required the package that has time zone data, such as DB11. | 4 credits |
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.ip2location.com/v2/?' . http_build_query([ 'ip' => '8.8.8.8', 'key' => 'YOUR_API_KEY', 'package' => 'WS24', 'format' => 'json', 'addon' => 'continent,country,region,city,geotargeting,country_groupings,time_zone_info', 'lang' => 'en', ])); curl_setopt($ch, CURLOPT_FAILONERROR, 1); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); var_dump($response);
try (java.util.Scanner s = new java.util.Scanner(new java.net.URL("https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en").openStream(), "UTF-8").useDelimiter("\\A")) { System.out.println(s.next()); } catch (java.io.IOException e) { e.printStackTrace(); }
Dim httpClient As New System.Net.Http.HttpClient Dim response As String = Await httpClient.GetStringAsync("https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en") Console.WriteLine($"{response}")
var httpClient = new HttpClient(); var response = await httpClient.GetStringAsync("https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en"); Console.WriteLine($"{response}");
from requests import get response = get('https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en').text print(format(response))
curl -s "https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en"
require "net/http" response = Net::HTTP.get(URI("https://api.ip2location.com/v2/?key={YOUR_API_KEY}&ip=8.8.8.8&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=en")) puts response
The IP Geolocation web service supports json and xml response format. Below please find the details:
https://api.ip2location.com/v2/?ip={IP_ADDRESS}&key={YOUR_API_KEY}&package=WS24&format=json&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=zh-cnResponse:
{ "country_code": "US", "country_name": "United States", "region_name": "California", "city_name": "Mountain View", "latitude": "37.405992", "longitude": "-122.078515", "zip_code": "94043", "time_zone": "-07:00", "isp": "Google LLC", "domain": "google.com", "net_speed": "T1", "idd_code": "1", "area_code": "650", "weather_station_code": "USCA0746", "weather_station_name": "Mountain View", "mcc": "-", "mnc": "-", "mobile_brand": "-", "elevation": "32", "usage_type": "DCH", "continent": { "name": "North america", "code": "NA", "hemisphere": [ "north", "east" ], "translations": { "zh-cn": "北美洲" } }, "country": { "name": "United States", "alpha3_code": "USA", "numeric_code": "840", "demonym": "Americans", "flag": "https://www.ip2location.com/assets/img/flags/us.png", "capital": "Washington, D.C.", "total_area": "9826675", "population": "326766748", "currency": { "code": "USD", "name": "United States Dollar", "symbol": "$" }, "language": { "code": "EN", "name": "English" }, "idd_code": "1", "tld": "us", "translations": { "zh-cn": "美国" } }, "region": { "name": "California", "code": "06", "translations": { "zh-cn": "加利福尼亚" } }, "city": { "name": "Mountain View", "translations": [] }, "geotargeting": { "metro": "807" }, "country_groupings": [ { "acronym": "Americas", "name": "Americas" }, { "acronym": "APEC", "name": "Asia-Pacific Economic Cooperation" }, { "acronym": "DAC", "name": "Development Assistance Committee" }, { "acronym": "G2", "name": "Group of Two" }, { "acronym": "G20", "name": "Group of Twenty" }, { "acronym": "G7", "name": "Group of Seven" }, { "acronym": "G8+5", "name": "G8+5" }, { "acronym": "NAFTA", "name": "North American Free Trade Agreement" }, { "acronym": "NALA", "name": "NALA" }, { "acronym": "OAS", "name": "Organization of American States" }, { "acronym": "OECD", "name": "Organisation for Economic Co-operation and Development" }, { "acronym": "P5", "name": "P5" }, { "acronym": "UN", "name": "United Nations" } ], "time_zone_info": { "olson": "America\/Los_Angeles", "current_time": "2019-03-03T23:06:07-08:00", "gmt_offset": -28800, "is_dst": "no", "sunrise": "06:50", "sunset": "19:32" } }
https://api.ip2location.com/v2/?ip={IP_ADDRESS}&key={YOUR_API_KEY}&package=WS24&format=xml&addon=continent,country,region,city,geotargeting,country_groupings,time_zone_info&lang=zh-cnResponse:
<?xml version="1.0" encoding="utf-8"?> <result> <country_code>US</country_code> <country_name>United States</country_name> <region_name>California</region_name> <city_name>Mountain View</city_name> <latitude>37.405992</latitude> <longitude>-122.078515</longitude> <zip_code>94043</zip_code> <time_zone>-07:00</time_zone> <isp>Google LLC</isp> <domain>google.com</domain> <net_speed>T1</net_speed> <idd_code>1</idd_code> <area_code>650</area_code> <weather_station_code>USCA0746</weather_station_code> <weather_station_name>Mountain View</weather_station_name> <mcc>-</mcc> <mnc>-</mnc> <mobile_brand>-</mobile_brand> <elevation>32</elevation> <usage_type>DCH</usage_type> <continent> <name>North america</name> <code>NA</code> <hemisphere> <item0>north</item0> <item1>east</item1> </hemisphere> <translations> <zh-cn>北美洲</zh-cn> </translations> </continent> <country> <name>United States</name> <alpha3_code>USA</alpha3_code> <numeric_code>840</numeric_code> <demonym>Americans</demonym> <flag>https://www.ip2location.com/assets/img/flags/us.png</flag> <capital>Washington, D.C.</capital> <total_area>9826675</total_area> <population>326766748</population> <currency> <code>USD</code> <name>United States Dollar</name> <symbol>$</symbol> </currency> <language> <code>EN</code> <name>English</name> </language> <idd_code>1</idd_code> <tld>us</tld> <translations> <zh-cn>美国</zh-cn> </translations> </country> <region> <name>California</name> <code>06</code> <translations> <zh-cn>加利福尼亚</zh-cn> </translations> </region> <city> <name>Mountain View</name> <translations/> </city> <geotargeting> <metro>807</metro> </geotargeting> <country_groupings> <item0> <acronym>Americas</acronym> <name>Americas</name> </item0> <item1> <acronym>APEC</acronym> <name>Asia-Pacific Economic Cooperation</name> </item1> <item2> <acronym>DAC</acronym> <name>Development Assistance Committee</name> </item2> <item3> <acronym>G2</acronym> <name>Group of Two</name> </item3> <item4> <acronym>G20</acronym> <name>Group of Twenty</name> </item4> <item5> <acronym>G7</acronym> <name>Group of Seven</name> </item5> <item6> <acronym>G8+5</acronym> <name>G8+5</name> </item6> <item7> <acronym>NAFTA</acronym> <name>North American Free Trade Agreement</name> </item7> <item8> <acronym>NALA</acronym> <name>NALA</name> </item8> <item9> <acronym>OAS</acronym> <name>Organization of American States</name> </item9> <item10> <acronym>OECD</acronym> <name>Organisation for Economic Co-operation and Development</name> </item10> <item11> <acronym>P5</acronym> <name>P5</name> </item11> <item12> <acronym>UN</acronym> <name>United Nations</name> </item12> </country_groupings> <time_zone_info> <olson>America/Los_Angeles</olson> <current_time>2019-03-03T23:31:01-08:00</current_time> <gmt_offset>-28800</gmt_offset> <is_dst>no</is_dst> <sunrise>06:50</sunrise> <sunset>19:32</sunset> </time_zone_info> </result>