canonical: https://jentic.com/apis/ipwhois.net/ipwhois

# IPWhois.net API

The IPWhois.net API returns the location, timezone, ISP, ASN, and connection type of an IPv4 or IPv6 address, including latitude, longitude, accuracy radius, and an is_eu flag. The same key also checks whether an address is listed on a DNS blacklist and resolves a MAC address or OUI to its registered vendor and address block. Paid plans add the full field set, batch lookups for IPs and blacklists, and a search for every OUI block registered to a vendor name, and every response carries a meta block with the key's plan and remaining quota.

## For AI agents

Geolocate IP addresses, check them against DNS blacklists, and identify the vendor behind a MAC address, with the key's remaining quota returned on every call.

## Scope

Does not return domain WHOIS records, geocode street addresses, or detect VPNs. Use for IP geolocation, DNS blacklist, and MAC vendor lookups only.

## Capabilities

- Geolocate an IPv4 or IPv6 address with country, city, postal_code, latitude, longitude, and accuracy_radius_km
- Read the ISP, ASN, and timezone of an address, or of the caller's own IP, trimmed to chosen paths with fields
- Check whether an IP is listed on a DNS blacklist, singly or in a paid batch
- Resolve a MAC address or OUI to its vendor company, block type, and randomized or multicast flags
- Find every OUI block registered to a vendor name on paid plans
- Read the key's plan, rate limit, and remaining quota without spending quota

## Use cases

### Agent-led IP and device investigation

An AI agent triaging a network alert needs to know where an address sits, whether it is blacklisted, and what hardware is on the local segment. Through Jentic the agent searches for 'look up an IP address', loads the IPWhois.net lookup, and then calls the blacklist and MAC reads with the same key attached at call time. It reports location, ISP, listing status, and device vendor in one answer.

Example prompt: Call GET `/ip/{ip}` for 203.0.113.7 with fields location,network.isp, then GET `/blacklist/{ip}` for the same address and GET `/mac/{mac}` for 00:1A:2B:3C:4D:5E, and summarise the results

### Mail server reputation checks

An email operations team checks whether its sending IPs appear on DNS blacklists before a campaign. The blacklist read returns a listed flag for one address, and on paid plans the batch read checks many IPs in one call with per-list detail.

Example prompt: Call POST `/blacklist/batch` with ips 198.51.100.10 and 198.51.100.11 and list any address where listed is true

### Network asset inventory

An IT administrator labelling devices from a switch's MAC table needs the manufacturer of each address. The MAC read returns the vendor company, country, and block type such as MA-L, and flags randomized and locally administered addresses so phones with private MACs are not mislabelled.

Example prompt: Call GET `/mac/{mac}` for each address in a list and record vendor.company, block.type, and is_randomized

### Quota-aware batch geolocation

A data job geolocating a day's access logs needs to stay inside its plan. The batch lookup takes an ips array on paid plans, and the usage read returns the key's plan, rate limit, and quota without counting against it, so the job can pace itself.

Example prompt: Call GET /usage to read the remaining quota, then call POST `/ip/batch` with ips 8.8.8.8 and 1.1.1.1 and store each result's country_code and asn

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/ip/{ip}` | Geolocate an IP address |
| GET | `/ip` | Look up the caller's own IP |
| POST | `/ip/batch` | Batch IP lookup (paid plans) |
| GET | `/blacklist/{ip}` | Check DNS blacklist status |
| GET | `/mac/{mac}` | Look up a MAC vendor |
| GET | `/mac/search` | Search OUI blocks by vendor (paid plans) |
| GET | `/usage` | Read plan and quota |

## Key resources

- **IP lookup** — Single, caller, and batch geolocation with location, timezone, and network blocks
- **Blacklist** — DNS blacklist status for one IP or a batch
- **MAC lookup** — Vendor and block for a MAC or OUI, plus vendor-name search
- **Usage** — Plan, rate limit, and quota of the key

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 42 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/ipwhois.net/ipwhois/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring IPWhois.net by hand means picking one of three ways to send the key, tracking which reads need a paid plan, and pacing calls to the per-second limit. Through Jentic you install once, import IPWhois.net from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** IPWhois.net splits IP, blacklist, MAC, and usage reads into separate operations, so a rule can bound your agent to the ones it needs, such as single IP lookups. You choose the operations it may call, so paid batch reads like POST `/ip/batch` are not included unless you add them.
- **Credential handling:** Your IPWhois.net key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up an IP address' or 'check an IP blacklist', and Jentic returns the matching IPWhois.net operation with its input schema so the agent calls the right endpoint.

## Related APIs

- **ipdata** — IP geolocation with threat and ASN data from a separate provider
- **IPstack** — IP to location lookups with currency and timezone data
- **IP2WHOIS** — Domain WHOIS records to pair with IP-level lookups

## FAQ

### What authentication does the IPWhois.net API use?

Per its OpenAPI spec, every call needs an API key, accepted in the X-API-Key header, as an Authorization: Bearer token, or in the key query parameter. One key works for the IP, blacklist, and MAC services. Through Jentic the key is stored by your own instance and attached at call time, so the agent never sees it.

### What are the rate limits for the IPWhois.net API?

The spec states a free key allows 1,000 IP, 1,000 blacklist, and 1,000 MAC lookups a day at 1 request per second with basic fields. Paid plans are metered per month: Starter 250,000 requests at 5 per second, Pro 1,500,000 at 15 per second, and Business 6,000,000 at 30 per second. See https://ipwhois.net/pricing for current prices.

### Can the IPWhois.net API identify a device from its MAC address?

Yes. GET `/mac/{mac}` returns the vendor company and country, the block type such as MA-L or MA-S, and flags for multicast, locally administered, and randomized addresses. On paid plans GET `/mac/search` lists the OUI blocks registered to a vendor name.

### Is there an IPWhois.net MCP server?

You don't need an MCP server to give your agent IPWhois.net. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the IP, blacklist, and MAC operations it needs without loading another server's tool definitions into its context.

### Can I limit what my agent is allowed to do with the IPWhois.net API?

Yes. Write a rule that allows only GET `/ip/{ip}` and GET /usage, for example, and the agent can geolocate single addresses and check its quota but cannot run the batch reads that spend paid allowance faster. Every call it makes is logged.

### How do I look up an IP address through Jentic?

Search Jentic for 'look up an IP address', load the GET `/ip/{ip}` operation, and execute it with the address and an optional fields value such as location,network.isp. To run it on your own infrastructure, install Jentic One from its GitHub repo.