# freeiplookupapi documentation

> freeiplookupapi resolves an IP address to basic geolocation data over a simple JSON REST API.

Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.freeiplookupapi.com

OpenAPI specification: https://freeiplookupapi.com/docs/openapi.yaml

---

Source: https://freeiplookupapi.com/docs

# Authentication & API key Information

Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://freeiplookupapi.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://freeiplookupapi.com/docs/llms.txt) / [llms-full.txt](https://freeiplookupapi.com/docs/llms-full.txt). There is also a hosted [MCP server](https://freeiplookupapi.com/docs/mcp) at `https://api.freeiplookupapi.com/mcp` that AI agents can connect to directly.

freeiplookupapi.com uses API keys to allow access to the API.

## Authentication methods

To authorize, you can use the following ways:

### GET query parameter

You can pass your API key along with every request by adding it as a query parameter `apikey`

This method could expose your API key in access logs and such.
Sending the API key via a header parameter as specified below circumvents this problem.

```bash
curl "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1&apikey=YOUR-APIKEY"
```

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1&apikey=YOUR-APIKEY");
oReq.send();
```

```php
$url = "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1&apikey=YOUR-APIKEY";

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);

$resp = curl_exec($curl);
var_dump($resp);

````

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1&apikey=YOUR-APIKEY"

resp = requests.get(url)

print(resp.status_code)
````

### HTTP Header

You can set a request header with the name `apikey`

```bash
curl "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1" \
    -H "apikey: YOUR-APIKEY" 
```

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1");
oReq.setRequestHeader("apikey", "YOUR-APIKEY");
oReq.send();
```

```php
$url = "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1";

$curl = curl_init($url);

$headers = array(
   "apikey: YOUR-APIKEY",
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

$resp = curl_exec($curl);
var_dump($resp);

````

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1"

headers = CaseInsensitiveDict()
headers["apikey"] = "YOUR-APIKEY"

resp = requests.get(url, headers=headers)

print(resp.status_code)
````

## Rate limit and quotas

You can use a certain number of requests per month, defined by your plan. Once you go over this quota, the API returns a `429` HTTP status code, and you either need to upgrade your plan or wait until the end of the month.

We enforce a minute rate limit for specific plans. If you exceed this, the API returns a `429` HTTP status code. You then have to wait until the end of the minute to make more requests.
Not every request counts

Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.

### Response Headers

We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period.

```HTTP
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
```

---

Source: https://freeiplookupapi.com/docs/info

# Info Endpoint

Checks the provided ip address (both `v4` & `v6` formats) and returns all available information.

**Request Method:** `GET`  
**Request URL:** `https://api.freeiplookupapi.com/v1/info`

## Request Parameters

| Parameter | Type                       | Mandatory  | Description                      |
| --------- | -------------------------- | ---------- | -------------------------------- |
| `apikey`  | _string_                   | ️ | Your API Key                     |
| `ip`      | _string_, _Path Parameter_ | ️ | The ip address you want to query |

## Example Request

```
https://api.freeiplookupapi.com/v1/info?apikey=xxxxxxxxxxxxx&ip=1.1.1.1
```

## Sample Response

```json
{
    "ip": "1.1.1.1",
    "country_code": "AU",
    "country_name": "Australia",
    "region_code": "AU-NSW",
    "region_name": "New South Wales",
    "city": "Sydney",
    "postal_code": "2000",
    "time_zone": "Australia/Sydney",
    "latitude": -33.86,
    "longitude": 151.2
}
```

---

Source: https://freeiplookupapi.com/docs/mcp

# MCP Server

freeiplookupapi ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required.

```
https://api.freeiplookupapi.com/mcp
```

The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.freeiplookupapi.com/register).

## Connect

Using Claude Code:

```bash
claude mcp add --transport http freeiplookupapi https://api.freeiplookupapi.com/mcp --header "apikey: YOUR_API_KEY"
```

Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...):

```json
{
  "mcpServers": {
    "freeiplookupapi": {
      "url": "https://api.freeiplookupapi.com/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}
```

## Available tools

The tools are generated from the same [OpenAPI specification](https://freeiplookupapi.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses.

| Tool | Endpoint | Description |
|---|---|---|
| `getInfo` | `GET /v1/info` | Look up an IP address |
| `getStatus` | `GET /v1/status` | Account quota status |

## Quotas and errors

Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed.

---

Source: https://freeiplookupapi.com/docs/status

# Status Endpoint

Returns your current quota

Requests to this endpoint do not count against your quota or rate limit

**Request Method:** `GET`  
**Request URL:** `https://api.freeiplookupapi.com/v1/status`

## Request Parameters

| Parameter | Type     | Mandatory  | Description  |
| --------- | -------- | ---------- | ------------ |
| `apikey`  | _string_ | ️ | Your API Key |

## Sample Response

```json
{
    "quotas": {
        "month": {
            "total": 300,
            "used": 71,
            "remaining": 229
        }
    }
}
```

---

Source: https://freeiplookupapi.com/docs/status-codes

# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code `200`

## API Error Codes

### 401

Invalid authentication credentials

### 403

You are not allowed to use this endpoint, please [upgrade your plan](https://app.cu# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code `200`

## API Error Codes

### 401

Invalid authentication credentials

### 403

You are not allowed to use this endpoint, please [upgrade your plan](https://app.freeiplookupapi.com/subscription).

### 404

A requested endpoint does not exist

### 422

Validation error, please check the list of validation errors: [here](#validation-errors)

### 429

You have hit your rate limit or your monthly limit. For more requests please [upgrade your plan](https://app.freeiplookupapi.com/subscription).

### 500

Internal Server Error - let us know: support@freeiplookupapi.com

## Validation errors

#### Invalid Ip

The `ip` must be a valid IP address

#### Missing ip

The `ip` parameter is required

#### Invalid language

The selected `language` is invalid  
Should be an ISO Alpha 2 Language Code for localising the ip data