API Documentation

whatsmy.fyi provides a single REST endpoint that returns IP address, geolocation, and connection metadata for the requesting IP. All data comes directly from the Cloudflare edge network — no third-party databases, no caching, no IP query logging.

• Free tier — 10,000 requests/day per key (Enterprise for unlimited)
• No IP query logging — we never store the IPs you look up
• Powered by Cloudflare Workers — global sub-50ms latency
• Three scopes: ip, geo, full

https://whatsmy.fyi/api/v1

All requests require an API key. Pass it as a Bearer token in the Authorization header (preferred) or as a key query parameter.

# Header (preferred)
curl https://whatsmy.fyi/api/v1/ip \
  -H "Authorization: Bearer wmf_your_api_key"

# Query parameter (fallback)
curl "https://whatsmy.fyi/api/v1/ip?key=wmf_your_api_key"

Don't have a key? Create a free account →

Each API key has a scope that controls which fields are returned. You choose the scope when creating a key and can change it anytime from the dashboard.

Returns IP metadata for the caller. The response shape depends on the key's scope.

Request

GET /api/v1/ip HTTP/1.1
Host: whatsmy.fyi
Authorization: Bearer wmf_your_api_key

Response by scope

{
  "status": "success",
  "ip": "203.0.113.42",
  "ipv6": null,
  "city": "Amsterdam",
  "region": "North Holland",
  "region_code": "NH",
  "country": "NL",
  "country_name": "Netherlands",
  "continent": "EU",
  "latitude": 52.374,
  "longitude": 4.8897,
  "timezone": "Europe/Amsterdam",
  "timezone_offset": 7200,
  "postal_code": "1011",
  "asn": 1101,
  "org": "SURF B.V.",
  "as": "AS1101 SURF B.V.",
  "is_eu": true,
  "currency": "EUR"
}

The Scope column shows which key scope includes each field. ALL = all scopes, GEO+ = geo and full, FULL = full only.

The free tier allows 10,000 requests per day per API key. The counter resets at midnight UTC. Rate limit status is returned on every response via headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9987
X-RateLimit-Reset: 1749081600  # Unix timestamp of next reset

When the limit is exceeded, the API returns a 429 response:

{
  "error": "rate_limit_exceeded",
  "message": "You have reached the free tier limit of 10,000 requests/day. Resets at midnight UTC.",
  "docs": "https://whatsmy.fyi/docs#rate-limits",
  "enterprise": "https://whatsmy.fyi/enterprise"
}

Need more? Enterprise plan →

Install the official @whatsmyfyi/sdk package for TypeScript-first access with automatic retries and full type definitions.

npm install @whatsmyfyi/sdk

import { WhatsMyFyi } from '@whatsmyfyi/sdk'

const client = new WhatsMyFyi({ apiKey: 'wmf_your_api_key' })

// Full response
const data = await client.ip.lookup()
console.log(data.city)      // "Amsterdam"
console.log(data.country)   // "NL"

// Quick helpers
const ip  = await client.ip.address()   // "203.0.113.42"
const loc = await client.ip.location()  // { city, country, countryCode, lat, lng }
const org = await client.ip.org()       // { asn, name }

• Zero dependencies — uses native fetch
• Works in Node.js, Deno, Bun, and the browser
• Auto-retry on 5xx with exponential backoff (max 3 attempts)
• Typed WhatsMyFyiError with code, message, status

The full OpenAPI 3.1 spec is available for import into Postman, Insomnia, or any compatible tool. In Postman, go to File → Import → Link and paste the URL below.

Add a badge to your README or website to show that you use the whatsmy.fyi API.

HTML

<a href="https://whatsmy.fyi">
  <img src="https://whatsmy.fyi/api/badge" alt="Powered by whatsmy.fyi" height="40" />
</a>

Markdown (GitHub README)

[![Powered by whatsmy.fyi](https://whatsmy.fyi/api/badge)](https://whatsmy.fyi)

Make a real API request right here — no account or API key needed. You'll see your own IP data returned directly from the Cloudflare edge.

Create a free account to get your API key in under a minute.