# Introduction
freeiplookupapi resolves an IPv4 or IPv6 address to basic geolocation data — country, region, city, postal code, timezone and coordinates — over a simple JSON REST API. It is the free tier of ipbase.com (opens new window), where you can upgrade for ASN, hosted domains, security signals and richer location data.
Building with an AI assistant? The full API is available as a machine-readable OpenAPI 3.1 specification (opens new window), and the documentation is published as llms.txt (opens new window) / llms-full.txt (opens new window). There is also a hosted MCP server (opens new window) at https://api.freeiplookupapi.com/mcp that AI agents can connect to directly.
# Authentication & API key Information
freeiplookupapi.com uses API keys to allow access to the API. All you need for your first request is a free API key — get yours here (opens new window), then try the curl example below.
# 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
WARNING
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.
Also keep in mind that anyone can extract an API key that is shipped in public front-end or mobile app code. If you cannot keep the key secret, proxy the requests through your own backend.
# HTTP Header
You can set a request header with the name apikey
# 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 also enforce a rate limit of 10 requests per minute — this applies to all 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.
Sandbox API keys
Requests made with a sandbox API key never count against your quota (their X-Cost header is 0). On the info endpoint, sandbox requests always return the data for 1.1.1.1 regardless of the ip parameter.
# Response Headers
We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period. Successful /v1/info responses also carry an X-Cost header with the number of requests the call counted against your quota (0 for sandbox API keys); /v1/status and error responses do not include X-Cost.
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 5000
X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 4880
X-Cost: 1
Grace and overage quotas
While your account is consuming a grace quota (after a failed subscription payment), the month headers are replaced by X-RateLimit-Limit-Grace-Month / X-RateLimit-Remaining-Grace-Month. When requests draw from an overage quota, the X-RateLimit-Limit-Overage-Month / X-RateLimit-Remaining-Overage-Month headers appear in addition to the (exhausted) month headers.