IP Geolocation API documentation
curl --request GET \
--url https://ipgeolocation.abstractapi.com/v1import requests
url = "https://ipgeolocation.abstractapi.com/v1"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://ipgeolocation.abstractapi.com/v1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ipgeolocation.abstractapi.com/v1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://ipgeolocation.abstractapi.com/v1"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://ipgeolocation.abstractapi.com/v1")
.asString();require 'uri'
require 'net/http'
url = URI("https://ipgeolocation.abstractapi.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"ip_address": "166.171.248.255",
"city": "San Jose",
"city_geoname_id": 5392171,
"region": "California",
"region_iso_code": "CA",
"region_geoname_id": 5332921,
"postal_code": "95141",
"country": "United States",
"country_code": "US",
"country_geoname_id": 6252001,
"country_is_eu": false,
"continent": "North America",
"continent_code": "NA",
"continent_geoname_id": 6255149,
"longitude": -121.7714,
"latitude": 37.1835,
"security": {
"is_vpn": false
},
"timezone": {
"name": "America/Los_Angeles",
"abbreviation": "PDT",
"gmt_offset": -7,
"current_time": "06:37:41",
"is_dst": true
},
"flag": {
"emoji": "🇺🇸",
"unicode": "U+1F1FA U+1F1F8",
"png": "https://static.abstractapi.com/country-flags/US_flag.png",
"svg": "https://static.abstractapi.com/country-flags/US_flag.svg"
},
"currency": {
"currency_name": "USD",
"currency_code": "USD"
},
"connection": {
"autonomous_system_number": 20057,
"autonomous_system_organization": "ATT-MOBILITY-LLC-AS20057",
"connection_type": "Cellular",
"isp_name": "AT&T Mobility LLC",
"organization_name": "Service Provider Corporation"
}
}
IP Geolocation API documentation
Endpoint reference for Abstract’s IP Geolocation API: base URL, request parameters, response fields, error codes and code samples for locating IP addresses in 190+ countries.
GET
/
v1
IP Geolocation API documentation
curl --request GET \
--url https://ipgeolocation.abstractapi.com/v1import requests
url = "https://ipgeolocation.abstractapi.com/v1"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://ipgeolocation.abstractapi.com/v1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ipgeolocation.abstractapi.com/v1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://ipgeolocation.abstractapi.com/v1"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://ipgeolocation.abstractapi.com/v1")
.asString();require 'uri'
require 'net/http'
url = URI("https://ipgeolocation.abstractapi.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"ip_address": "166.171.248.255",
"city": "San Jose",
"city_geoname_id": 5392171,
"region": "California",
"region_iso_code": "CA",
"region_geoname_id": 5332921,
"postal_code": "95141",
"country": "United States",
"country_code": "US",
"country_geoname_id": 6252001,
"country_is_eu": false,
"continent": "North America",
"continent_code": "NA",
"continent_geoname_id": 6255149,
"longitude": -121.7714,
"latitude": 37.1835,
"security": {
"is_vpn": false
},
"timezone": {
"name": "America/Los_Angeles",
"abbreviation": "PDT",
"gmt_offset": -7,
"current_time": "06:37:41",
"is_dst": true
},
"flag": {
"emoji": "🇺🇸",
"unicode": "U+1F1FA U+1F1F8",
"png": "https://static.abstractapi.com/country-flags/US_flag.png",
"svg": "https://static.abstractapi.com/country-flags/US_flag.svg"
},
"currency": {
"currency_name": "USD",
"currency_code": "USD"
},
"connection": {
"autonomous_system_number": 20057,
"autonomous_system_organization": "ATT-MOBILITY-LLC-AS20057",
"connection_type": "Cellular",
"isp_name": "AT&T Mobility LLC",
"organization_name": "Service Provider Corporation"
}
}
This page is the technical reference. For plans, the free tier and a live demo, see the IP Geolocation API product page.
Getting started
REST
The IP Geolocation API, like all of Abstract’s APIs, is organized around REST. It is designed to use predictable, resource-oriented URLs and to use HTTP status codes to indicate errors.HTTPS
The IP Geolocation API requires all communications to be secured with TLS 1.2 or greater.API Versions
All of Abstract’s APIs are versioned. The IP Geolocation API is currently on Version 1.Your API Key
Your API key is your unique authentication key to be used to access Abstract’s IP Geolocation API. Note that each of Abstract’s APIs has a unique API key, so you will need different keys to access the IP Geolocation and Email Validation APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.Base URL
https://ipgeolocation.abstractapi.com/v1/
Validation endpoint
Abstract’s IP Geolocation API simply requires your unique API key and will automatically detect the IP address from the client where it is called. You can also append the “ip_address” parameter to specify the IP to analyze:https://ipgeolocation.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 166.171.248.255 (optional)
{
"ip_address": "166.171.248.255",
"city": "San Jose",
"city_geoname_id": 5392171,
"region": "California",
"region_iso_code": "CA",
"region_geoname_id": 5332921,
"postal_code": "95141",
"country": "United States",
"country_code": "US",
"country_geoname_id": 6252001,
"country_is_eu": false,
"continent": "North America",
"continent_code": "NA",
"continent_geoname_id": 6255149,
"longitude": -121.7714,
"latitude": 37.1835,
"security": {
"is_vpn": false
},
"timezone": {
"name": "America/Los_Angeles",
"abbreviation": "PDT",
"gmt_offset": -7,
"current_time": "06:37:41",
"is_dst": true
},
"flag": {
"emoji": "🇺🇸",
"unicode": "U+1F1FA U+1F1F8",
"png": "https://static.abstractapi.com/country-flags/US_flag.png",
"svg": "https://static.abstractapi.com/country-flags/US_flag.svg"
},
"currency": {
"currency_name": "USD",
"currency_code": "USD"
},
"connection": {
"autonomous_system_number": 20057,
"autonomous_system_organization": "ATT-MOBILITY-LLC-AS20057",
"connection_type": "Cellular",
"isp_name": "AT&T Mobility LLC",
"organization_name": "Service Provider Corporation"
}
}
Request parameters
String
required
Your unique API key. Note that each user has unique API keys for each of Abstract’s APIs, so your IP Geolocation API key will not work for your Email Validation API, for example.
String
The IP address to geolocate. Both IPv4 and IPv6 addresses are supported. Note that if you leave this parameter blank, the service will geolocate the IP address from which the request was made.
String
You can chose to only receive a few fields from the JSON response. To do so, you can include a fields value in the query parameters with a comma separated list of the top-level keys you want to be returned. For example, adding ?fields=city will return only the city in the JSON response.
Response parameters
The API response is returned in a universal and lightweight JSON format.String
The IP address submitted for geolocation.
String
City’s name.
String
City’s geoname ID.
String
State or province in which the the city is located.
Char[2]
State or province’s ISO 3166-2 code.
String
State or province’s geoname ID.
String
ZIP or postal code.
String
Country’s name.
Char[2]
Country’s ISO 3166-1 alpha-2 code.
String
Country’s geoname ID.
Boolean
True if the country is in the EU, false if it is not.
String
Continent’s name.
Char[2]
2 letter continent code: AF, AS, EU, NA, OC, SA, AN.
String
Continent’s geoname ID.
Float
Decimal of the longitude.
Float
Decimal of the latitude.
Boolean
Whether the IP address is being used from a VPN or using a proxy
String
Timezone’s name from the IANA Time Zone Database.
String
Timezone’s abbreviation, also from the IANA Time Zone Database.
String
Timezone’s offset from Greenwich Mean Time (GMT).
String
Current time in the local time zone.
Boolean
True if the location is currently in Daylight Savings Time (DST).
String
Link to a hosted version of the country’s flag in SVG format.
String
Link to a hosted version of the country’s flag in PNG format.
String
Country’s flag as an emoji.
String
Country’s flag in unicode.
String
The currency’s name.
String
The currency’s code in ISO 4217 format.
String
Type of network connection: Dialup, Cable/DSL, Cellular, Corporate.
Uint32
Autonomous System number.
String
Autonomous System Organization name.
String
Internet Service Provider (ISP) name.
String
Organization name.
Limiting response fields
You can choose to only receive a few fields from the JSON response. To do so, you can include a fields value in the query parameters with a comma separated list of the top-level keys you want to be returned. For example, a request to only get the country and city of an IP will look like this:https://ipgeolocation.abstractapi.com/v1/
? api_key = YOUR_API_KEY
& ip_address = 166.171.248.255
& fields = country,city
{
"country": "United States",
"city": "Modesto"
}
Use cases
Geolocating a website visitor
To request the geolocation from an IP address, simply include your unique API key in the template below. Note that you don’t need to know the IP of the visitor to make the request.$.getJSON("https://ipgeolocation.abstractapi.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
console.log(data.ip_address);
console.log(data.country);
})
Response and error codes
Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.| Code | Type | Details |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 204 | OK | Their is no location data for the submitted IP. |
| 400 | Bad request | Bad request. |
| 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. |
| 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) |
| 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
| 500 | Internal server error | The request could not be completed due to an error on the server side. |
| 503 | Service unavailable | The server was unavailable. |
Country Codes
Below is a list of two-letter ISO 3166 Alpha 2 country codes that are used in the response. View this list in a CSV.| Country name | Country code |
|---|---|
| Afghanistan | AF |
| Albania | AL |
| Algeria | DZ |
| American Samoa | AS |
| Andorra | AD |
| Angola | AO |
| Anguilla | AI |
| Antigua and Barbuda | AG |
| Argentina | AR |
| Armenia | AM |
| Aruba | AW |
| Australia | AU |
| Austria | AT |
| Azerbaijan | AZ |
| Bahrain | BH |
| Bangladesh | BD |
| Barbados | BB |
| Belarus | BY |
| Belgium | BE |
| Belize | BZ |
| Benin | BJ |
| Bermuda | BM |
| Bhutan | BT |
| Bolivia | BO |
| Bosnia and Herzegovina | BA |
| Botswana | BW |
| Brazil | BR |
| British Virgin Islands | VG |
| Brunei | BN |
| Bulgaria | BG |
| Burkina Faso | BF |
| Burundi | BI |
| Cabo Verde | CV |
| Cambodia | KH |
| Cameroon | CM |
| Canada | CA |
| Cayman Islands | KY |
| Central African Republic | CF |
| Chad | TD |
| Chile | CL |
| China | CN |
| Colombia | CO |
| Comoros | KM |
| Congo | CG |
| Congo Democratic Republic | CD |
| Cook Islands | CK |
| Costa Rica | CR |
| Cote d’Ivoire | CI |
| Croatia | HR |
| Cuba | CU |
| Curaçao | CW |
| Cyprus | CY |
| Czechia | CZ |
| Denmark | DK |
| Djibouti | DJ |
| Dominica | DM |
| Dominican Republic | DO |
| East Timor | TL |
| Ecuador | EC |
| Egypt | EG |
| El Salvador | SV |
| Equatorial Guinea | GQ |
| Eritrea | ER |
| Estonia | EE |
| eSwatini | SZ |
| Ethiopia | ET |
| Falkland Islands | FK |
| Faroe Islands | FO |
| Fiji | FJ |
| Finland | FI |
| France | FR |
| French Guiana | GF |
| French Polynesia | PF |
| Gabon | GA |
| Gambia | GM |
| Georgia | GE |
| Germany | DE |
| Ghana | GH |
| Gibraltar | GI |
| Greece | GR |
| Greenland | GL |
| Grenada | GD |
| Guadeloupe | GP |
| Guam | GU |
| Guatemala | GT |
| Guernsey | GG |
| Guinea | GN |
| Guinea-Bissau | GW |
| Guyana | GY |
| Haiti | HT |
| Honduras | HN |
| Hong Kong | HK |
| Hungary | HU |
| Iceland | IS |
| India | IN |
| Indonesia | ID |
| Iran | IR |
| Iraq | IQ |
| Ireland | IE |
| Isle of Man | IM |
| Israel | IL |
| Italy | IT |
| Jamaica | JM |
| Japan | JP |
| Jersey | JE |
| Jordan | JO |
| Kazakhstan | KZ |
| Kenya | KE |
| Kiribati | KI |
| Kosovo | XK |
| Kuwait | KW |
| Kyrgyzstan | KG |
| Laos | LA |
| Latvia | LV |
| Lebanon | LB |
| Lesotho | LS |
| Liberia | LR |
| Libya | LY |
| Liechtenstein | LI |
| Lithuania | LT |
| Luxembourg | LU |
| Macau | MO |
| Madagascar | MG |
| Malawi | MW |
| Malaysia | MY |
| Maldives | MV |
| Mali | ML |
| Malta | MT |
| Marshall Islands | MH |
| Martinique | MQ |
| Mauritania | MR |
| Mauritius | MU |
| Mayotte | YT |
| Mexico | MX |
| Micronesia | FM |
| Moldova | MD |
| Monaco | MC |
| Mongolia | MN |
| Montenegro | ME |
| Montserrat | MS |
| Morocco | MA |
| Mozambique | MZ |
| Myanmar | MM |
| Namibia | NA |
| Nauru | NR |
| Nepal | NP |
| Netherlands | NL |
| New Caledonia | NC |
| New Zealand | NZ |
| Nicaragua | NI |
| Niger | NE |
| Nigeria | NG |
| North Korea | KP |
| North Macedonia | MK |
| Northern Mariana Islands | MP |
| Norway | NO |
| Oman | OM |
| Pakistan | PK |
| Palau | PW |
| Panama | PA |
| Papua New Guinea | PG |
| Paraguay | PY |
| Peru | PE |
| Philippines | PH |
| Poland | PL |
| Portugal | PT |
| Puerto Rico | PR |
| Qatar | QA |
| Reunion | RE |
| Romania | RO |
| Russia | RE |
| Rwanda | RW |
| Saint Helena | SH |
| Saint Kitts and Nevis | KN |
| Saint Lucia | LC |
| Saint Martin | MF |
| Saint Pierre and Miquelon | PM |
| Saint Vincent and the Grenadines | VC |
| Samoa | WS |
| San Marino | SM |
| Sao Tome and Principe | ST |
| Saudi Arabia | SA |
| Senegal | SN |
| Serbia | RS |
| Seychelles | SC |
| Sierra Leone | SL |
| Singapore | SG |
| Sint Maarten | SX |
| Slovakia | SK |
| Slovenia | SI |
| Solomon Islands | SB |
| Somalia | SO |
| South Africa | ZA |
| South Korea | KR |
| South Sudan | SS |
| Spain | ES |
| Sri Lanka | LK |
| St. Barts | BL |
| Sudan | SD |
| Suriname | SR |
| Sweden | SE |
| Switzerland | CH |
| Syria | SY |
| Taiwan | TW |
| Tajikistan | TJ |
| Tanzania | TZ |
| Thailand | TH |
| The Bahamas | BH |
| Togo | TG |
| Tonga | TO |
| Trinidad and Tobago | TT |
| Tunisia | TN |
| Turkey | TR |
| Turkmenistan | TM |
| Turks and Caicos Islands | TC |
| Tuvalu | TV |
| Uganda | UG |
| Ukraine | UA |
| United Arab Emirates | AE |
| United Kingdom | GB |
| United States | US |
| Uruguay | UY |
| US Virgin Islands | VI |
| Uzbekistan | UZ |
| Vanuatu | VU |
| Vatican City (Holy See) | VA |
| Venezuela | VE |
| Vietnam | VN |
| Wallis and Futuna | WF |
| Yemen | YE |
| Zambia | ZM |
| Zimbabwe | ZW |