Product introduction
1. Fast Track
To get following response put this:
Linux and macOS:
curl -d '{"ips": ["8.8.8.8"]}' -H "Authorization: Api-Key $APIKey" https://iplocation.services/api/ip-geolocation/
Windows:
curl -d "{"ips": ["8.8.8.8"]}" -H "Authorization: Api-Key %APIKey%" https://iplocation.services/api/ip-geolocation/
{
}
]
}
"results": [
{
"ip":
"8.8.8.8",
"country_name":
"United States",
"continent_name":
"North America",
"latitude":
37.751,
"longitude":
-97.822,
"type":
"IPv4",
...
{
"results": [
{
"ip":
"8.8.8.8",
"net_mask":
"255.255.255.255",
"private":
false,
"global":
true,
"multicast":
false,
"reserved":
false,
"type":
"IPv4",
"continent_code":
"NA",
"continent_name":
"North America",
"country_code":
"US",
"country_name":
"United States",
"region_name":
null,
"city":
null,
"zip":
null,
"latitude":
37.751,
"longitude":
-97.822,
"is_eu":
false,
"timezone":
{
"id":
"America/Chicago",
"utc":
null,
},
"location":
{
"country_name":
"United States",
"is_eu":
false,
"capital":
"Washington D.C.",
"languages":
["en"],
"native_name":
"United States",
"iso":
{
"alpha2":
"US",
"alpha3":
"USA"
},
"currencies":
["USD", "USN", "USS"],
"country_population":
319259000,
"calling_code":
["1"],
"region":
"Americas",
"subregion":
"Northern America",
"wiki":
"http://en.wikipedia.org/wiki/united_states_of_america"
},
"currency":
{
"USD":
{
"name":
"United States dollar",
"symbol":
"$"
},
"USN":
{
"name":
null,
"symbol":
null
},
"USS":
{
"name":
null,
"symbol":
null
}
},
"connection":
{
"asn":
15169,
"asn_cidr":
8.8.8.0/24,
"asn_country_code":
"US"
"asn_description":
null,
"isp":
"GOOGLE"
}
}
]
}
2. Querying
Below are shown the ways of querying API. Both IPv4 and IPv6 addresses are supported and can be mixed in a single request.
| Description | Query |
Response |
|---|---|---|
| Single - put interested IP into array and get full response | curl -d '{"ips": ["IP1"]}' -H "Authorization: Api-Key $APIKey" https://iplocation.services/api/ip-geolocation/ |
Single full response as in point 1 |
|
Single filtered - put interested IP into array and define
filters to get interested in data |
curl -d '{"ips": ["IP1"], "filters": ["country_name",
"city"]}' -H "Authorization: Api-Key $APIKey"
https://iplocation.services/api/ip-geolocation/ |
{"results":[
{"country_name":"United States","city":"Houston"}] } |
| Multi* - put interested IPs into array and get full response | curl -d '{"ips": ["IP1","IP2"]}' -H "Authorization: Api-Key $APIKey" https://iplocation.services/api/ip-geolocation/ | {"results":[{results_IP1},{results_IP2}]} |
|
Multi filtered*- put interested IPs into array and define
filters to get interested in data |
curl -d '{"ips": ["IP1","IP2"], "filters": ["country_name", "city"]}' -H "Authorization: Api-Key $APIKey" https://iplocation.services/api/ip-geolocation/ | {"results"[ {"country_name":"UnitedStates", "city":"Houston"},{"country_name":"UnitedStates","city":"California"}]} |
*Multi response available only in paid plans
3. Response Codes and Error Handling
Successful Requests
The IP Geolocation API returns a 200 HTTP status code for successful API requests. The response body will contain the requested geolocation data.
Unsuccessful Requests
In case of a bad or illegal request, the IP Geolocation API returns an appropriate 4xx HTTP status code along with a descriptive error message explaining why the error occurred.
Possible error codes include:
| Code | Description |
|---|---|
|
400 Bad Request |
Invalid input data |
|
401 Unauthorized |
Invalid API key |
|
415 Unsupported Media Type |
Incorrect Content-Type. The supported media are application/json and application/x-www-form-urlencoded |
|
422 Unprocessable Entity |
One or more invalid IP addresses provided. The response will include results for valid IPs and an error message listing the invalid IPs in the format: "error": "Invalid IP addresses: {'IP1','IP2'}" |
|
429 Too Many Requests |
Usage limit exceeded |
4. Authorization
Authorization for this API is handled via an API key. To obtain your key:
1. Log in to your account
2. Navigate to the APIKeys view
3. Generate a new API key
Once generated, include this key in your API requests as shown in the examples above. Keep your API key secure and do not share it publicly.
5. Security
We prioritize the security of your data. All our API endpoints, regardless of your plan type, are protected by:
- HTTPS encryption: Every connection is secured using SSL/TLS.
- Universal coverage: This applies to all users, including those on free plans.
This ensures that your API requests and responses are always encrypted, maintaining the confidentiality and integrity of your data during transmission.
6. Response field detail description
|
Field name |
Type |
Description | Can be empty? |
|---|---|---|---|
| ip | string | IP address used for the geolocation lookup | No |
| net_mask | string | Network mask associated with the IP address | No |
| private | boolean | Indicates if the IP is part of a private network range | No |
| global | boolean | Indicates if the IP is globally routable on the public internet | No |
| multicast | boolean | Indicates if the IP is part of a multicast address range | No |
| reserved | boolean | Indicates if the IP is part of a reserved address range | No |
| type | string | Version of the IP protocol (IPv4 or IPv6) | No |
| continent_code | string | Two-letter code representing the continent | No |
| continent_name | string | Full name of the continent | No |
| country_code | string | Two-letter ISO country code | No |
| country_name | string | Full name of the country | No |
| region_name | string | Name of the region (state, province, etc.) | Yes |
| city | string | Name of the city | Yes |
| zip | string | Postal code or ZIP code of the location | Yes |
| longitude | float | Longitude coordinate of the estimated location | No |
| timezone.id | string | Identifier for the time zone of the location | No |
| timezone.utc | string | UTC offset of the time zone | Yes |
| location.country_name | string | Full name of the country | No |
| location.is_eu | boolean | Indicates whether the country is in the European Union | No |
| location.capital | string | Name of the country's capital city | No |
| location.languages | array of strings | Language codes spoken in the country | No |
| location.native_name | string | Native name of the country | No |
| location.iso.alpha2 | string | Two-letter ISO country code | No |
| location.iso.alpha3 | string | Three-letter ISO country code | No |
| location.currencies | array of strings | Currency codes used in the country | No |
| location.country_population | integer | Population of the country | No |
| location.calling_code | array of strings | International calling codes for the country | No |
| location.region | string | Broader geographical region of the country | No |
| location.subregion | string | More specific subregion of the country | No |
| location.wiki | string | Link to the Wikipedia page about the country | No |
| currency.[code].name | string | Name of the currency for each currency code | Yes |
| currency.[code].symbol | string | Symbol of the currency for each currency code | Yes |
| connection.asn | integer | Autonomous System Number associated with the IP address | No |
| connection.asn_cidr | string | ASN CIDR refers to a parameter that denotes the Classless Inter-Domain Routing (CIDR) notation of an IP address range associated with a specific Autonomous System Number (ASN), allowing for the identification and management of routing information for IP addresses within that ASN. | No |
| connection.asn_country_code | string | Two-letter code representing the continent of asn | No |
| connection.asn_description | string | ASN description | Yes |
| connection.isp | string | Name of the Internet Service Provider or organization associated with the IP address | No |
"At iplocation.services, we're on a mission to empower businesses and developers with the tools and insights to navigate the digital landscape, making IP intelligence simple, powerful, and actionable."
Contact