---
title: IP Geolocation API - City, Country, Coordinates & ISP Data
version: 1.0.0
description: Retrieve real-time geolocation and network intelligence for a single IPv4 or IPv6 address or hostname. Returns location (continent, country, region, city, coordinates, timezone), network (ASN, ISP/company, route), and currency data by default. Pass `include=security,hostname,liveHostname,hostnameFallbackLive,user_agent,abuse,dma_code,geo_accuracy` (or `include=*`) to add threat-intelligence scoring, reverse DNS resolution, parsed User-Agent details, abuse contact info, DMA code, or geolocation accuracy metadata as additional response blocks. Reserved, bogon, or unrecognized IP addresses return a `423` or `404` error instead of partial location data.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v2.0
paths: 1
operations: 1
schemas: 16
---

## Table of Contents

- [IP Geolocation API - City, Country, Coordinates & ISP Data v1.0.0](#ip-geolocation-api-city-country-coordinates-isp-data-v100)
  - [Authentication](#authentication)
  - [IP Geolocation APIs](#ip-geolocation-apis)
    - [ipLookup](#iplookup)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [IpLookupResponse](#iplookupresponse)
    - [Location](#location)
    - [CountryMetadata](#countrymetadata)
    - [Network](#network)
    - [Asn](#asn)
    - [Company](#company)
    - [Currency](#currency)
    - [Security](#security)
    - [Abuse](#abuse)
    - [DstTransition](#dsttransition)
    - [TimeZone](#timezone)
    - [Device](#device)
    - [Engine](#engine)
    - [OperatingSystem](#operatingsystem)
    - [UserAgent](#useragent)
    - [ErrorResponse](#errorresponse)



# IP Geolocation API - City, Country, Coordinates & ISP Data v1.0.0

Retrieve real-time geolocation and network intelligence for a single IPv4 or IPv6 address or hostname. Returns location (continent, country, region, city, coordinates, timezone), network (ASN, ISP/company, route), and currency data by default. Pass `include=security,hostname,liveHostname,hostnameFallbackLive,user_agent,abuse,dma_code,geo_accuracy` (or `include=*`) to add threat-intelligence scoring, reverse DNS resolution, parsed User-Agent details, abuse contact info, DMA code, or geolocation accuracy metadata as additional response blocks. Reserved, bogon, or unrecognized IP addresses return a `423` or `404` error instead of partial location data.

Base URLs:

* [https://api.apifreaks.com/v2.0](https://api.apifreaks.com/v2.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## IP Geolocation APIs

### ipLookup

`GET /geolocation/lookup`

*Retrieve real-time and accurate IP geolocation and threat intelligence information for an IPv4 or IPv6 address*

Get detailed IP geolocation data for an IP address including country, city, timezone, currency, and optional threat intelligence and user-agent information.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response.|
|ip|query|string|false|IPv4, IPv6, or hostname for geolocation lookup.|
|lang|query|string|false|Response language for location fields. Default: en.|
|fields|query|string|false|Comma-separated list of fields to include in response. For example, `location` includes all location fields, `location.city` is a specific field.|
|excludes|query|string|false|Comma-separated list of fields to exclude from response.|
|include|query|string|false|Comma-separated list of additional data modules to include. Possible values: security (threat intelligence), hostname (IP-Hostname lookup), liveHostname (live hostname lookup), hostnameFallbackLive (hostname with live fallback), user_agent (parse User-Agent header), abuse (abuse contact info), dma_code (DMA code), geo_accuracy (accuracy_radius, confidence, locality), * (all modules).|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|
|lang|en|
|lang|de|
|lang|ru|
|lang|ja|
|lang|fr|
|lang|cn|
|lang|es|
|lang|cs|
|lang|it|
|lang|ko|
|lang|fa|
|lang|pt|

> Example responses

> Successful geolocation response

```json
{
  "ip": "8.8.8.8",
  "location": {
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_name_official": "United States of America",
    "country_capital": "Washington, D.C.",
    "state_prov": "California",
    "state_code": "US-CA",
    "district": "Santa Clara",
    "city": "Mountain View",
    "zipcode": "94043-1351",
    "latitude": "37.42240",
    "longitude": "-122.08421",
    "is_eu": false,
    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
    "geoname_id": "6301403",
    "country_emoji": "🇺🇸"
  },
  "country_metadata": {
    "calling_code": "+1",
    "tld": ".us",
    "languages": [
      "en-US",
      "es-US",
      "haw",
      "fr"
    ]
  },
  "network": {
    "connection_type": "",
    "route": "8.8.8.0/24",
    "is_anycast": true
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$"
  },
  "asn": {
    "as_number": "AS15169",
    "organization": "Google LLC",
    "country": "US",
    "type": "BUSINESS",
    "domain": "google.com",
    "date_allocated": "2000-03-30",
    "rir": "ARIN"
  },
  "company": {
    "name": "Google LLC",
    "type": "HOSTING",
    "domain": "google.com"
  },
  "time_zone": {
    "name": "America/Los_Angeles",
    "offset": -8,
    "offset_with_dst": -7,
    "current_time": "2026-07-08 03:03:31.835-0700",
    "current_time_unix": 1783505011.835,
    "current_tz_abbreviation": "PDT",
    "current_tz_full_name": "Pacific Daylight Time",
    "standard_tz_abbreviation": "PST",
    "standard_tz_full_name": "Pacific Standard Time",
    "is_dst": true,
    "dst_savings": 1,
    "dst_exists": true,
    "dst_tz_abbreviation": "PDT",
    "dst_tz_full_name": "Pacific Daylight Time",
    "dst_start": {
      "utc_time": "2026-03-08 TIME 10:00",
      "duration": "+1.00H",
      "gap": true,
      "date_time_after": "2026-03-08 TIME 03:00",
      "date_time_before": "2026-03-08 TIME 02:00",
      "overlap": false
    },
    "dst_end": {
      "utc_time": "2026-11-01 TIME 09:00",
      "duration": "-1.00H",
      "gap": false,
      "date_time_after": "2026-11-01 TIME 01:00",
      "date_time_before": "2026-11-01 TIME 02:00",
      "overlap": true
    }
  }
}
```

> Bad Request — Invalid or missing parameters

```json
{
  "message": "The request was unacceptable. Typically due to missing or invalid parameters."
}
```

> Not Found — IP address not in database

```json
{
  "message": "Provided IP address '255.255.255.255' doesn't exist in our database."
}
```

> Locked — Bogon or reserved IP address

```json
{
  "message": "'127.0.0.1' is a bogon (Internet Assigned Numbers Authority) IP address."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful geolocation response|[IpLookupResponse](#iplookupresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid or missing parameters|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — IP address not in database|[ErrorResponse](#errorresponse)|
|423|[Locked](https://tools.ietf.org/html/rfc2518#section-10.4)|Locked — Bogon or reserved IP address|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|423|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### IpLookupResponse

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ip|string|true|none|The IP address used for the lookup (IPv4 or IPv6).|
|domain|string|false|none|The input domain, returned only for domain-based lookups.|
|hostname|string|false|none|Reverse DNS hostname (PTR) for the input IP; returns the input IP if not resolvable.|
|location|[Location](#location)|false|none|Geographic location information for the IP.|
|country_metadata|[CountryMetadata](#countrymetadata)|false|none|Country-specific metadata.|
|network|[Network](#network)|false|none|Network information for the IP.|
|asn|[Asn](#asn)|false|none|Autonomous System details for the IP.|
|company|[Company](#company)|false|none|Company or ISP information mapped to the IP address.|
|currency|[Currency](#currency)|false|none|Currency information for the IP's country.|
|security|[Security](#security)|false|none|Threat intelligence and security information for the IP.|
|abuse|[Abuse](#abuse)|false|none|Abuse contact information for the IP.|
|time_zone|[TimeZone](#timezone)|false|none|Time zone information for the IP's location.|
|user_agent|[UserAgent](#useragent)|false|none|Parsed User-Agent details from the request.|

### Location

Geographic location information for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|continent_code|string|true|none|2-letter code of the continent.|
|continent_name|string|true|none|Name of the continent.|
|country_code2|string|true|none|Country code (ISO 3166-1 alpha-2) of the country.|
|country_code3|string|true|none|Country code (ISO 3166-1 alpha-3) of the country.|
|country_name|string|true|none|Name of the country.|
|country_name_official|string|true|none|Official name (ISO 3166) of the country.|
|country_capital|string|true|none|Name of the country's capital.|
|state_prov|string|false|none|Name of the state/province/region.|
|state_code|string|false|none|Code of the state/province/region.|
|district|string|false|none|Name of the district or county.|
|city|string|false|none|Name of the city.|
|locality|string|false|none|A more specific area in city or it can be same as city.|
|accuracy_radius|string|false|none|Circular radius in Km, where the IP address location can be found.|
|confidence|string|false|none|Confidence level of the location match (e.g., low, medium, high).|
|dma_code|string|false|none|Designated Market Area (DMA) code used in the United States for media marketing.|
|zipcode|string|false|none|ZIP/Postal code of the place.|
|latitude|string|true|none|Latitude of the place.|
|longitude|string|true|none|Longitude of the place.|
|is_eu|boolean|true|none|Is the country belong to European Union?|
|country_flag|string(uri)|true|none|URL to get the country flag.|
|geoname_id|string|false|none|Geoname ID of the place from geonames.org.|
|country_emoji|string|false|none|Emoji of the Country flag.|

### CountryMetadata

Country-specific metadata.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|calling_code|string|true|none|Calling code/Dialing code of the country.|
|tld|string|true|none|Top Level Domain Name (TLD) of the country, which is also called ccTLD.|
|languages|[string]|true|none|List of the languages' codes, spoken in the country.|

### Network

Network information for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|connection_type|string|false|none|Network access type classification (e.g., DSL, Cable, Mobile, 5G) when available.|
|route|string|false|none|Network prefix in CIDR notation that contains the IP.|
|is_anycast|boolean|false|none|true if the IP is anycast (same IP announced from multiple locations).|

### Asn

Autonomous System details for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|as_number|string|false|none|ASN identifier in AS<number> format associated with the IP's network.|
|organization|string|false|none|ASN operator name.|
|country|string|false|none|ASN registration country as ISO 3166-1 alpha-2.|
|type|string|false|none|ASN category (ISP, HOSTING, BUSINESS, etc.).|
|domain|string|false|none|ASN operator domain name.|
|date_allocated|string|false|none|ASN allocation date in YYYY-MM-DD format.|
|rir|string|false|none|Regional Internet Registry that allocated the ASN.|

### Company

Company or ISP information mapped to the IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Company name mapped to the IP.|
|type|string|false|none|Company category (ISP, HOSTING, BUSINESS, etc.).|
|domain|string|false|none|Company domain name.|

### Currency

Currency information for the IP's country.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|string|false|none|Currency code (ISO 4217).|
|name|string|false|none|Currency name (ISO 4217).|
|symbol|string|false|none|Currency symbol.|

### Security

Threat intelligence and security information for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|threat_score|number|true|none|Aggregate risk score from 0 to 100.|
|is_tor|boolean|true|none|true if the IP matches a Tor exit node.|
|is_proxy|boolean|true|none|true if the IP is associated with a proxy service.|
|proxy_provider_names|[string]|false|none|Detected proxy provider names.|
|proxy_confidence_score|number|true|none|Proxy detection confidence from 0 to 100.|
|proxy_last_seen|string|false|none|Last observed proxy activity date in YYYY-MM-DD.|
|is_residential_proxy|boolean|true|none|true if the IP is linked to a residential proxy network.|
|is_vpn|boolean|true|none|true if the IP is associated with a VPN service.|
|vpn_provider_names|[string]|false|none|Detected VPN provider names.|
|vpn_confidence_score|number|true|none|VPN detection confidence from 0 to 100.|
|vpn_last_seen|string|false|none|Last observed VPN activity date in YYYY-MM-DD.|
|is_relay|boolean|true|none|true if the IP is associated with a relay network.|
|relay_provider_name|string|false|none|Relay provider name.|
|is_anonymous|boolean|true|none|true if any anonymity signal is present.|
|is_known_attacker|boolean|true|none|true if the IP is flagged for known attacker behavior.|
|is_bot|boolean|true|none|true if the IP is associated with bot activity.|
|is_spam|boolean|true|none|true if the IP is associated with spam activity.|
|is_cloud_provider|boolean|true|none|true if the IP belongs to a cloud provider range.|
|cloud_provider_name|string|false|none|Cloud provider name.|

### Abuse

Abuse contact information for the IP.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|route|string|false|none|Abuse-handling IP range in CIDR notation.|
|country|string|false|none|ISO 3166-1 alpha-2 country code of the abuse contact.|
|name|string|false|none|Display name for the abuse contact.|
|organization|string|false|none|Organization name for the abuse contact.|
|kind|string|false|none|Contact type: group or individual.|
|address|string|false|none|Registered address of the organization owning the IP.|
|emails|[string]|false|none|Abuse contact email addresses.|
|phone_numbers|[string]|false|none|Abuse contact phone numbers.|

### DstTransition

DST transition details (used for both the DST start and DST end transitions).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|utc_time|string|false|none|DST transition moment in UTC.|
|duration|string|false|none|Clock change at the DST transition, in hours.|
|gap|boolean|false|none|true if local time jumps forward (some times do not exist).|
|date_time_after|string|false|none|Local date/time immediately after the DST transition.|
|date_time_before|string|false|none|Local date/time immediately before the DST transition.|
|overlap|boolean|false|none|true if local times repeat around the DST transition.|

### TimeZone

Time zone information for the IP's location.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|Time zone in IANA TZDB format.|
|offset|number(float)|true|none|Standard time UTC offset in hours.|
|offset_with_dst|number(float)|true|none|Current effective UTC offset in hours, including DST.|
|current_time|string|true|none|Local date/time in YYYY-MM-DD HH:mm:ss.SSS±ZZZZ format.|
|current_time_unix|number(float)|true|none|Local time as Unix epoch seconds.|
|current_tz_abbreviation|string|false|none|Current time zone abbreviation.|
|current_tz_full_name|string|false|none|Current time zone full name.|
|standard_tz_abbreviation|string|false|none|Standard (non-DST) abbreviation.|
|standard_tz_full_name|string|false|none|Standard (non-DST) full name.|
|is_dst|boolean|true|none|true if DST is active.|
|dst_savings|number(float)|true|none|DST shift amount in hours.|
|dst_exists|boolean|true|none|true if the time zone observes DST.|
|dst_tz_abbreviation|string|false|none|DST abbreviation when DST is active.|
|dst_tz_full_name|string|false|none|DST full name when DST is active.|
|dst_start|[DstTransition](#dsttransition)|false|none|DST transition details (used for both the DST start and DST end transitions).|
|dst_end|[DstTransition](#dsttransition)|false|none|DST transition details (used for both the DST start and DST end transitions).|

### Device

Device details.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Detected device label.|
|type|string|false|none|Device category (Desktop, Mobile, Tablet, Bot).|
|brand|string|false|none|Device vendor/brand.|
|cpu|string|false|none|CPU / architecture string.|

### Engine

Rendering engine details.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Rendering engine name.|
|type|string|false|none|Engine category.|
|version|string|false|none|Full engine version string.|
|version_major|string|false|none|Major engine version.|

### OperatingSystem

Operating system details.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Operating system name.|
|type|string|false|none|OS category (Desktop, Mobile, Server).|
|version|string|false|none|OS version string.|
|version_major|string|false|none|Major OS version.|
|build|string|false|none|OS build identifier.|

### UserAgent

Parsed User-Agent details from the request.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|user_agent_string|string|false|none|Raw User-Agent string used for parsing.|
|name|string|false|none|Detected user agent product name.|
|type|string|false|none|User agent category (e.g., Browser, Mobile App, Bot).|
|version|string|false|none|Full product version string.|
|version_major|string|false|none|Major version extracted from version.|
|device|[Device](#device)|false|none|Device details.|
|engine|[Engine](#engine)|false|none|Rendering engine details.|
|operating_system|[OperatingSystem](#operatingsystem)|false|none|Operating system details.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|