GET
/
v1
curl --request GET \
  --url https://ipgeolocation.abstractapi.com/v1
{
    "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"
    }
}

It’s very simple to use: you only need to submit your API key and an IP address, and the API will respond with the location of that IP including postal code, city, region, country and lat/long data.

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)

This was a successful request, so the IP address and details associated with it are returned below:

{
    "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

api_key
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.

ip_address
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.

fields
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.

ip_address
String

The IP address submitted for geolocation.

city
String

City’s name.

city_geoname_id
String

City’s geoname ID.

region
String

State or province in which the the city is located.

region_iso_code
Char[2]

State or province’s ISO 3166-2 code.

region_geoname_id
String

State or province’s geoname ID.

postal_code
String

ZIP or postal code.

country
String

Country’s name.

country_code
Char[2]

Country’s ISO 3166-1 alpha-2 code.

country_geoname_id
String

Country’s geoname ID.

country_is_eu
Boolean

True if the country is in the EU, false if it is not.

continent
String

Continent’s name.

continent_code
Char[2]

2 letter continent code: AF, AS, EU, NA, OC, SA, AN.

continent_geoname_id
String

Continent’s geoname ID.

longitude
Float

Decimal of the longitude.

latitude
Float

Decimal of the latitude.

security.is_vpn
Boolean

Whether the IP address is using from a VPN or using a proxy

timezone.name
String

Timezone’s name from the IANA Time Zone Database.

timezone.abbreviation
String

Timezone’s abbreviation, also from the IANA Time Zone Database.

timezone.gmt_offset
String

Timezone’s offset from Greenwich Mean Time (GMT).

timezone.current_time
String

Current time in the local time zone.

timezone.is_dst
Boolean

True if the location is currently in Daylight Savings Time (DST).

flag.svg
String

Link to a hosted version of the country’s flag in SVG format.

flag.png
String

Link to a hosted version of the country’s flag in PNG format.

flag.emoji
String

Country’s flag as an emoji.

flag.unicode
String

Country’s flag in unicode.

currency.currency_name
String

The currency’s name.

currency.currency_code
String

The currency’s code in ISO 4217 format.

connection.connection_type
String

Type of network connection: Dialup, Cable/DSL, Cellular, Corporate.

connection.autonomous_system_number
Uint32

Autonomous System number.

connection.autonomous_system_organization
String

Autonomous System Organization name.

connection.isp_name
String

Internet Service Provider (ISP) name.

connection.organization_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

The response would look like this:

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

That’s all your need to get the geolocation and other data from a visitor! There is only one required parameter: your unique API key.

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.

CodeTypeDetails
200OKEverything worked as expected.
204OKTheir is no location data for the submitted IP.
400Bad requestBad request.
401UnauthorizedThe request was unacceptable. Typically due to the API key missing or incorrect.
422Quota reachedThe request was aborted due to insufficient API credits. (Free plans)
429Too many requestsThe 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.
500Internal server errorThe request could not be completed due to an error on the server side.
503Service unavailableThe 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 nameCountry code
AfghanistanAF
AlbaniaAL
AlgeriaDZ
American SamoaAS
AndorraAD
AngolaAO
AnguillaAI
Antigua and BarbudaAG
ArgentinaAR
ArmeniaAM
ArubaAW
AustraliaAU
AustriaAT
AzerbaijanAZ
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BelizeBZ
BeninBJ
BermudaBM
BhutanBT
BoliviaBO
Bosnia and HerzegovinaBA
BotswanaBW
BrazilBR
British Virgin IslandsVG
BruneiBN
BulgariaBG
Burkina FasoBF
BurundiBI
Cabo VerdeCV
CambodiaKH
CameroonCM
CanadaCA
Cayman IslandsKY
Central African RepublicCF
ChadTD
ChileCL
ChinaCN
ColombiaCO
ComorosKM
CongoCG
Congo Democratic RepublicCD
Cook IslandsCK
Costa RicaCR
Cote d’IvoireCI
CroatiaHR
CubaCU
CuraçaoCW
CyprusCY
CzechiaCZ
DenmarkDK
DjiboutiDJ
DominicaDM
Dominican RepublicDO
East TimorTL
EcuadorEC
EgyptEG
El SalvadorSV
Equatorial GuineaGQ
EritreaER
EstoniaEE
eSwatiniSZ
EthiopiaET
Falkland IslandsFK
Faroe IslandsFO
FijiFJ
FinlandFI
FranceFR
French GuianaGF
French PolynesiaPF
GabonGA
GambiaGM
GeorgiaGE
GermanyDE
GhanaGH
GibraltarGI
GreeceGR
GreenlandGL
GrenadaGD
GuadeloupeGP
GuamGU
GuatemalaGT
GuernseyGG
GuineaGN
Guinea-BissauGW
GuyanaGY
HaitiHT
HondurasHN
Hong KongHK
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
IranIR
IraqIQ
IrelandIE
Isle of ManIM
IsraelIL
ItalyIT
JamaicaJM
JapanJP
JerseyJE
JordanJO
KazakhstanKZ
KenyaKE
KiribatiKI
KosovoXK
KuwaitKW
KyrgyzstanKG
LaosLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LibyaLY
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacauMO
MadagascarMG
MalawiMW
MalaysiaMY
MaldivesMV
MaliML
MaltaMT
Marshall IslandsMH
MartiniqueMQ
MauritaniaMR
MauritiusMU
MayotteYT
MexicoMX
MicronesiaFM
MoldovaMD
MonacoMC
MongoliaMN
MontenegroME
MontserratMS
MoroccoMA
MozambiqueMZ
MyanmarMM
NamibiaNA
NauruNR
NepalNP
NetherlandsNL
New CaledoniaNC
New ZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
North KoreaKP
North MacedoniaMK
Northern Mariana IslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
PanamaPA
Papua New GuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PolandPL
PortugalPT
Puerto RicoPR
QatarQA
ReunionRE
RomaniaRO
RussiaRE
RwandaRW
Saint HelenaSH
Saint Kitts and NevisKN
Saint LuciaLC
Saint MartinMF
Saint Pierre and MiquelonPM
Saint Vincent and the GrenadinesVC
SamoaWS
San MarinoSM
Sao Tome and PrincipeST
Saudi ArabiaSA
SenegalSN
SerbiaRS
SeychellesSC
Sierra LeoneSL
SingaporeSG
Sint MaartenSX
SlovakiaSK
SloveniaSI
Solomon IslandsSB
SomaliaSO
South AfricaZA
South KoreaKR
South SudanSS
SpainES
Sri LankaLK
St. BartsBL
SudanSD
SurinameSR
SwedenSE
SwitzerlandCH
SyriaSY
TaiwanTW
TajikistanTJ
TanzaniaTZ
ThailandTH
The BahamasBH
TogoTG
TongaTO
Trinidad and TobagoTT
TunisiaTN
TurkeyTR
TurkmenistanTM
Turks and Caicos IslandsTC
TuvaluTV
UgandaUG
UkraineUA
United Arab EmiratesAE
United KingdomGB
United StatesUS
UruguayUY
US Virgin IslandsVI
UzbekistanUZ
VanuatuVU
Vatican City (Holy See)VA
VenezuelaVE
VietnamVN
Wallis and FutunaWF
YemenYE
ZambiaZM
ZimbabweZW

Code samples and libraries

Please see the top of this page for code samples for these languages and more. If we’re missing a code sample, or if you’d like to contribute a code sample or library in exchange for free credits, email us at: team@abstractapi.com

Other notes

A note on metered billing: Each individual IP you submit counts as a credit used. Credits are also counted per request, not per successful response. So if you submit a request for the (invalid) IP address “kasj8929hs”, that still counts as 1 credit.