By the end of this guide you’ll have an API key, a working request, and parsed location data in your language of choice.
Sign up at ipstack.com/signup/free with an email address. No credit card is required. The free IP API plan includes 100 requests a month, enough to complete this guide many times over.
Your access key appears on the dashboard as soon as you sign up. It is the only credential the API uses, passed as the access_key query parameter on every request.
Keep it server-side. Store the key in an environment variable like IPSTACK_KEY. A key in browser JavaScript is visible to anyone who opens the page source.
# cURL first: this is how you test curl "https://api.ipstack.com/134.201.250.155?access_key=YOUR_KEY"
The Run in Postman collection is a ready-made client for testing. Free-plan keys call the API over http://, and HTTPS is included from Basic ($12.99/mo).
The response is a plain object, so use the data the way you would any parsed JSON. Here is the same visible result in each language: a location label built from two fields the free plan returns.
// "Los Angeles, US" const { city, country_code } = data; const label = `${city}, ${country_code}`; document.querySelector("#geo-label").textContent = label;
All three endpoints share one base URL, and everything in this guide works on each of them.
| Endpoint | URL shape | Use it when |
|---|---|---|
| Standard lookup | GET /{ip} | You have an address and want its profile. The workhorse for enrichment and checks. |
| Requester lookup | GET /check | The address you care about is whoever is calling. No IP extraction on your side. |
| Bulk lookup PROFESSIONAL+ | GET /{ip1},{ip2},… | Up to 50 addresses per request for logs, backfills, and batch enrichment. |
For bulk and continuous check workflows, see the real-time IP lookup API.
Append any of these to the query string. They combine freely.
| Parameter | Example | What it does |
|---|---|---|
| fields | &fields=ip,city,country_code | Returns only the listed fields; dot notation reaches nested ones |
| hostname | &hostname=1 | Adds reverse DNS for the address |
| security | &security=1 | Includes the security block on plans that carry it |
| language | &language=de | Localizes name fields into a supported language |
| output | &output=xml | Switches the response body from JSON to XML |
| callback | &callback=myHandler | Wraps the response for JSONP consumers |
For output formats and payload trimming in depth, see the JSON IP API page.
Every error returns success: false plus a code. These three cover almost every first-week issue.
| Code | What it means | How to fix it |
|---|---|---|
| 101 | Access key missing or invalid | Confirm the environment variable loads and matches the key on your dashboard; watch for trailing whitespace |
| 103 | Invalid API function | Check the endpoint path for typos; only /{ip}, /check, and comma-separated bulk shapes exist |
| 104 | Monthly request limit reached | Wait for the monthly reset or upgrade from the dashboard; your key and code stay the same |
The documentation lists every error code.
Global IP Data in One GET Request
One request returns location, network, and threat data for any IPv4 or IPv6 address.
Cache what you look up
An IP's location changes slowly. A cache keyed by address with a sensible TTL cuts request volume without hurting freshness.
Keep the key out of clients
Keep the key in an environment variable on the server, and give browser code a proxy route instead. Anything shipped to a client is public.
Handle 104 before it happens
Catch the quota error, degrade gracefully, and alert yourself at 80% usage instead of discovering the limit in production. Upgrade options are on the pricing page.
Watch the status page
The API status page shows current availability; point your own uptime monitor at your integration too.
IPstack's MCP server takes the same access key, and a connected coding agent can run these lookups while you work.
What the 100+ fields mean and what teams build with them, industry by industry.
IP geolocation APIThe exact free-tier terms, the free-vs-paid matrix, and when upgrading starts to matter.
free IP API planResponse format, output switches, payload trimming, and copy-paste parsing recipes.
JSON IP APISign up at ipstack.com/signup/free with an email address; no credit card is needed. Your access key appears on the dashboard right after signup. Copy it into an environment variable and you are ready for Step 2 above; one key works across every endpoint.
Use /check: it resolves the address behind the request automatically, so GET https://api.ipstack.com/check?access_key=YOUR_KEY returns your visitor’s profile without you reading their IP first. It works on every plan. Prefer it whenever the address you care about belongs to whoever is calling you right now.
Join the addresses with commas in the URL path: https://api.ipstack.com/{ip1},{ip2},{ip3}?access_key=YOUR_KEY. The response becomes an array of result objects in the order you sent them, up to 50 per request on Professional+. Loop the array and parse each entry exactly like a single result.
Error 101 means the access key is missing or invalid: check that the environment variable actually loads and matches the dashboard. Error 104 means you hit your plan’s monthly request limit: wait for the reset or upgrade from the dashboard. Neither fix requires code changes, since your key and endpoints stay the same.
Yes: add output=xml to any request URL and the same data comes back as XML. Everything else stays identical, including field names and plan scope. Use it for legacy systems that expect XML; leave it off everywhere else, since JSON is the default and parses everywhere.
Any language that can send an HTTP GET works, which is effectively all of them. Official SDKs live at ipstack.com/sdk/, and the Postman collection gives you a no-code client for testing. The samples in this guide cover cURL, JavaScript, Python, and PHP.
Everything in this guide runs on a key you can create right now. Sign up, paste, and watch the JSON come back.
