Name: IP Geolocation API - Location, Timezone, Currency Data
Brand: quotalink
SKU: api-quotalink-ip-geolocation-api
Availability: InStock
Author: API Market

李乐

## Overview

IP Geolocation API resolves any public IPv4 or IPv6 address to its location and network owner: country, region, city, coordinates, IANA timezone, ISP name and ASN. One call, flat JSON, no provider account to set up.

Reserved and private ranges are rejected explicitly rather than returning misleading data, so you can trust that a successful response describes a real, routable address.

## Features

- **IPv4 and IPv6**: both address families resolve through the same endpoint.
- **Location data**: country, region, city and decimal coordinates.
- **Network ownership**: ISP name and ASN, useful for identifying hosting providers and carriers.
- **IANA timezone**: identifiers such as `America/Los_Angeles`, ready to pass to a date library.
- **EU flag**: an `is_eu` boolean for quick GDPR-related routing decisions.
- **Explicit range validation**: private and reserved addresses return a clear `400` instead of a guess.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Content localisation**: pick a language, currency display or regional storefront on first page load.
- **Fraud and risk scoring**: compare the network owner and country against the account's stated location.
- **Analytics enrichment**: attach country, region and ASN to request logs.
- **Compliance routing**: use `is_eu` to decide which consent flow or data region applies.
- **Bot and datacentre detection**: the `isp` and `asn` fields make hosting-provider traffic easy to spot.
- **Scheduling and display**: render timestamps in the visitor's local timezone.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/ip-geolocation-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Endpoints

#### GET /lookup/{ip}

Resolves a single public IP address.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ip` | path | string | Yes | Public IPv4 or IPv6 address |

```bash
curl "https://prod.api.market/api/v1/quotalink/ip-geolocation-api/lookup/8.8.8.8" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "ip": "8.8.8.8",
  "country": "United States",
  "region": "California",
  "city": "San Jose",
  "latitude": 37.3361663,
  "longitude": -121.8905913,
  "timezone": "America/Los_Angeles",
  "isp": "Google LLC",
  "asn": 15169,
  "is_eu": false,
  "currency": ""
}
```

IPv6 works identically:

```bash
curl "https://prod.api.market/api/v1/quotalink/ip-geolocation-api/lookup/2606:4700:4700::1111" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

| Field | Type | Notes |
| --- | --- | --- |
| `ip` | string | The address that was resolved, echoed back |
| `country` | string | Country name, not an ISO code |
| `region` | string | First level administrative division |
| `city` | string | City name |
| `latitude` / `longitude` | number | Decimal degrees, city-level accuracy |
| `timezone` | string | IANA timezone identifier |
| `isp` | string | Network owner or carrier |
| `asn` | integer | Autonomous System Number |
| `is_eu` | boolean | Whether the country is in the European Union |
| `currency` | string | Present in the schema but currently returned empty |

Addresses outside the public routable space are rejected: private ranges such as `192.168.1.1` return `400` with `{"error":"Reserved range"}`, and malformed input returns `400` with `{"error":"Invalid IP address"}`. Addresses in documentation ranges that carry no registry data return a `200` with null fields.

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```bash
curl "https://prod.api.market/api/v1/quotalink/ip-geolocation-api/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{ "service": "ip-geolocation-api", "status": "ok" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Invalid IP, reserved range, or missing `x-api-market-key` header | Validate the address and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `404` | No address supplied in the path | Call `/lookup/{ip}`, not `/lookup/` |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream error | Retry with exponential backoff |

## Rate Limits

Quotas apply per billing period:

- **Free**: 1,000 API units, hard limit, up to 10 requests per second. Requests are rejected once the quota is spent.
- **Pro**: 10,000 API units per month, soft limit with overage billed per additional call, up to 50 requests per second.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with an `error` field:

```json
{ "error": "Invalid IP address" }
```

```json
{ "error": "Reserved range" }
```

Validate addresses before calling if your input comes from user data, since malformed values still consume a request. When reading a client IP from behind a proxy, take the first public address in `X-Forwarded-For`, because the chain often begins with a private range that this API will reject.

## Implementation Guide

### Example Code

```python
import ipaddress
import requests

BASE = "https://prod.api.market/api/v1/quotalink/ip-geolocation-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def locate(ip):
    addr = ipaddress.ip_address(ip)
    if addr.is_private or addr.is_reserved or addr.is_loopback:
        return None
    r = requests.get(f"{BASE}/lookup/{ip}", headers=HEADERS, timeout=15)
    if r.status_code == 400:
        return None
    r.raise_for_status()
    return r.json()

info = locate("8.8.8.8")
print(info["city"], info["country"], info["isp"], info["timezone"])
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/ip-geolocation-api";

async function locate(ip) {
  const res = await fetch(`${BASE}/lookup/${encodeURIComponent(ip)}`, {
    headers: { "x-api-market-key": process.env.API_MARKET_KEY },
  });
  if (res.status === 400) return null;
  if (!res.ok) throw new Error(`Lookup failed: ${res.status}`);
  const data = await res.json();
  return {
    country: data.country,
    city: data.city,
    timezone: data.timezone,
    network: `${data.isp} (AS${data.asn})`,
    inEu: data.is_eu,
  };
}
```

### Performance Optimization

- Cache by IP address. Allocations change rarely, so a 24 hour cache removes almost all repeat lookups for returning visitors.
- Filter private and reserved ranges client-side before calling. Those requests can only fail, and they still count against your quota.
- Resolve once per session and store the result on the session record instead of looking up on every request.
- Stay within your plan's rate limit when enriching logs in bulk: 10 requests per second on Free and 50 on Pro.

## FAQ

**Do I need an account with QuotaLink to use this API?**

No. Your API.market key is the only credential required.

**Does it support IPv6?**

Yes. IPv4 and IPv6 addresses both resolve through `/lookup/{ip}` with the same response shape.

**Why is `currency` empty?**

The field is present in the response schema but is not currently populated. Derive currency from `country` if you need it.

**Why did a private address return a 400?**

Private and reserved ranges such as `192.168.x.x` and `10.x.x.x` carry no public registry data, so they are rejected rather than guessed at.

**Is `country` an ISO code?**

No, it is the full country name, for example `United States`. There is no ISO country code field in the response.

**How accurate are the coordinates?**

City level. IP geolocation identifies the network's registered location, not the device, so treat the coordinates as approximate.

**What is `is_eu` for?**

It flags whether the resolved country is in the European Union, which is convenient for choosing a consent or data-residency path.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Get precise location, timezone, currency, and ISP information for any IP address worldwide. Support for IPv4 and IPv6.