The IP Geolocation API, like all of Abstract's APIs, is organized around REST. It is designed to use predictable, resource-oriented URL's and to use HTTP status codes to indicate errors.
The IP Geolocation API requires all communications to be secured TLS 1.2 or greater.
All of Abstract's API are versioned. The IP Geolocation API is currently on Version 1.
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 API, for example. To authenticate your requests, you will need to append your API key to the base URL.
Your unique API key. Note that each user has unique API keys for each of Abstract's APIs, so your User Avatar API key will not work for as your IP Geolocation API key, for example.
The IP address to geolocate. Both IPv4 and IPv6 addresses are supported.
The requested IP address
City's geoname ID.
State or province in which the the city is located.
State or province's ISO 3166-2 code.
State or province's geoname ID.
ZIP or postal code.
Country's ISO 3166-1 alpha-2 code.
Country's geoname ID.
True if the country is in the EU, false if it is not.
2 letter continent code: AF, AS, EU, NA, OC, SA, AN
Continent's geoname ID.
Decimal of the longitude.
Decimal of the latitude.
connection > connection_type
Type of network connection: Dialup, Cable/DSL, Cellular, Corporate
connection > autonomous_system_number
connection > autonomous_system_organization
Autonomous System Organization name.
connection > isp_name
Internet Service Provider (ISP) name.
connection > organization_name
timezone > name
Timezone's name from the IANA Time Zone Database.
timezone > abbreviation
Timezone's abbreviation, also from the IANA Time Zone Database.
timezone > gmt_offset
Timezone's offset from Greenwich Mean Time (GMT).
timezone > current_time
Current time in the local time zone.
timezone > is_dst
True if the location is currently in Daylight Savings Time (DST).
flag > svg
Link to a hosted version of the country's flag in SVG format.
flag > png
Link to a hosted version of the country's flag in PNG format.
flag > emoji
Country's flag as an emoji.
flag > unicode
Country's flag in unicode.
To request the geolocation from an IP address,, simply include your unique API key and the IP address you would like to check.
? apikey = YOUR_UNIQUE_API_KEY
& ip = 220.127.116.11
That's all your need to get the geolocation and other data from an IP address! There are only two required parameters: the IP address and your unique API key.
The API response is returned in a universal and lightweight JSON format. Below is an example of a response for an IP address location in France.
"name": "Central European Time",
"unicode": "U+1F1EB U+1F1F7",
"autonomous_system_organization": "France Telecom - Orange, FR",
"isp_name": "Orange S.A.",
"organization_name": "Internet OM"
Each individual IP you submit counts as a credit used. So, if you submit 20 different IP addresses in a single request, that will count as 20 credits against your monthly quota. 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.
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.
Everything worked as expected.
The request was unacceptable. Typically due to the API key missing or incorrect.
Internal Server Error
The request could not be completed due to an error on the server side.
The server was unavailable.
The Abstract IP Geolocation API takes an IP address and translates it into a location, as well as many other details, such as an address, timezone, and more.
IP geolocation and IP lookup are terms that are usually used interchangeably. However, individual providers of IP Geolocation / IP lookup services will often provide different information in their response. For example, some will simply provide raw geocoordinates, such as 33° 56' 34.0476'' N and 118° 24' 36.1512'' W, while others while provide additional information, such as the best guess at the location’s address, timezone, and more.
Typically an Internet Service Provider (ISP) will have a particular range of IP addresses that they work with. These ISPs can delegate these different IP addresses to the various users and devices as they connect to the internet. IP geolocation works by looking up a particular IP against the IP ranges owned by particular ISP’s in a given area. This method is similar to how determining the carrier of a particular phone number works in the Abstract Phone Validation API, for example.
While IP Geolocation can be an incredibly powerful and useful tool for developers and web services, there are several drawbacks and limitations to be aware of. First is that IP addresses have limited accuracy. An ISP may shuffle in IP among several users in a given area. Similarly, the location of the IP may not be the exact location of the user using the device associated with that IP. This can be common if a user is using a mobile phone, such as can be detected using the Phone Validation API. Finally, users can use a variety of services, such as virtual private networks or VPN’s, to mask their real IP.
The HTML5 geolocation API, which is able to provide an almost GPS-like location and a much greater amount of precision. However, unlike pure IP based geolocation, the HTML5 geolocation requires a user’s explicit consent. Unless it’s very clear to a user why you need that info and that it’s valuable to the user, it’s unlikely that information will be provided.
In its simplest form, IP geolocation is looking up an individual IP against a series of tables that map various IP ranges to ISP’s and locations. Regional internet registries, such as the African Network Information Centre and American Registry for Internet Numbers. Additional information is added constantly to the fundamental dataset, which is regularly cleaned and cross checked to ensure accuracy.
There are many powerful use cases for IP geolocation API’s and data. These include but are not limited to:
These are just some sample use cases. If you’re interested in producing a case study with Abstract to share how you’re using our IP geolocation API in exchange for some free credits, please contact us at team at abstractapi.com.
We’re constantly working to increase the coverage and accuracy of our data, which improves every week. Currently we support more than 2.25 million unique locations as well as 250,000+ cities and other geographic entities around the world.
Our IP geolocation database is updated at least once a week, as we get new information about each IP block. We take care of keeping that data updated and cleaned so you can focus on providing great geolocation-related services and experiences to your users.
While we always strive to provide the most accurate and up to date information possible. However, if you notice anything inaccurate or missing in our data, please email us at: team at hellobonsai.com. If we can identify and replicate the incorrect data you’re seeing, we’ll give you extra credits for reporting it :)
August 12, 2020
Optimizations that reduced response times 15%
July 20, 2020
Improved accuracy of city and region names to geoname ID's
July 4, 2020
Country flags updated
Updated the PNG and SVG country flags with higher quality images.
July 2, 2020
ASO Database Updated
Our database of names of Autonomous Service Organizations (ASO's) can been updated with the latest data.
Each of our API's has a free plan as well as several paid options, which offer a greater number of requests, a higher level of data quality, and greater speed for higher prices. Please see the page above or sign into your account to view pricing for each API.
Absolutely! We want you to try before you buy. Each of our API's has a free tier with a generous usage allowance for you to try the product out and verify that the speed and data quality work for you.
We use Stripe to accept payment via major debit and credit cards (Visa, Mastercard, American Express). If you cannot use those payment methods, then contact us at team at abstractapi.com to arrange for an alternative payment method.
Yes, you can upgrade or downgrade your subscription at any time by visiting your dashboard. If you upgrade in the middle of a billing cycle, you will be charged a pro-rated amount for your new plan through the end of the billing cycle.
Yes, all of our subscriptions are month to month. You can cancel at any time, and you will not be charged again at the end of your billing cycle.
You can cancel your subscription at any time from your dashboard. Once canceled, your subscription will be active until the end your current billing cycle, and then it will be automatically moved to the free plan.
If your API usage exceeds the monthly limit set by your plan, then you will be charged a fee for each call over your limit. At the end of your billing period, your usage will reset again.
We do offer enterprise plans with custom features and pricing in limited circumstances. If our public pricing plans don't work for you, then contact us (team at abstractapi.com) and we'll work something out.
While we don't normally offer discounts, we do make exceptions for certain types of users and use cases. If you are a student or are engaged in academic work, or are working on a non-profit or open source project, we're happy to offer you discounts for our API's. Just email us at team at abstractapi.com.
All of our plans are currently paid month to month. We will be launching annual plans at a discount soon. If you're interested in an annual plan in the meantime, just contact us and we'll set you up.
We will typically attempt to charge your payment method up to three times after it fails. If we're still unable to collect payment, then your subscription will be automatically canceled and you'll be moved to the free plan.
Yes, a paid tier of our API may be used in conjunction with a commercial project. The free tiers of our API's may not be used in commercial projects.