Skip to main content
GET
IP Geolocation API
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

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:
This was a successful request, so the IP address and details associated with it are returned below:

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 being used 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:
The response would look like this:

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

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.

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.