Cotoax IP Lookup API

Getting started

Send a GET request with the address in the ip query parameter. Every response is application/json.

curl

curl "https://ip.cotoax.com/api?ip=8.8.8.8"

Pass ip=0.0.0.0 to look up the address the request comes from.

The API sends no CORS headers, so browsers block calls from other websites. Call it from your server, a script or the command line.

Rate limits

Limits apply per client, shared across both versions:

5 requests per 10 seconds
20 requests per minute

IPv4 clients are counted per address and IPv6 clients per /64 network. There is also a shared ceiling on total traffic, so lookups can be refused briefly during heavy load even under your own limit.

When a limit is hit, the request still returns 200, but every field holds the string "API Rate Limited", and a Retry-After header gives the seconds to wait. Check for it before trusting the data.

v1 Full lookup

GET /api?ip=address

Everything we know about the address: location down to postal code, coordinates, hostname and network owner, plus proxy/VPN detection.

Parameters

ip required: An IPv4 or IPv6 address. 0.0.0.0 means the caller's own address.

Try it

Example response

{"ip":"8.8.8.8","hostname":"dns.google","city":"Mountain View","region":"California","country":"United States","loc":"37.422,-122.085","org":"AS15169 Google LLC","postal":"94043","timezone":"America/Los_Angeles","proxy":true,"type":"Proxy"}

Response fields

Field	Type	Description
`ip`	string	The address that was looked up.
`hostname`	string	Reverse DNS name.
`city`	string	City name.
`region`	string	State, province or region.
`country`	string	Country name.
`loc`	string	Coordinates as `"latitude,longitude"`.
`org`	string	ASN and network owner, e.g. `"AS15169 Google LLC"`.
`postal`	string	Postal or ZIP code.
`timezone`	string	IANA time zone, e.g. `"Europe/Berlin"`.
`proxy`	boolean	`true` when the address is a VPN, proxy, Tor exit, hosting or compromised address.
`type`	string	The connection type. See connection types.

Fields we have no data for are left out of the response, not sent as null.

v2 Network lookup

GET /api/v2?ip=address

A lighter response focused on the network: ASN and owner split into separate fields, plus country and continent codes. Use it when you need to group or filter by network or region.

Parameters

ip required: An IPv4 or IPv6 address. 0.0.0.0 means the caller's own address.

Try it

Example response

{"ip":"2606:4700:4700::1111","asn":"AS13335","as_name":"Cloudflare, Inc.","country_code":"CA","country":"Canada","continent_code":"NA","continent":"North America","proxy":true,"type":"Hosting"}

Response fields

Field	Type	Description
`ip`	string	The address that was looked up.
`asn`	string	Autonomous system number, e.g. `"AS13335"`.
`as_name`	string	Name of the network owner.
`country_code`	string	ISO 3166-1 alpha-2 country code.
`country`	string	Country name.
`continent_code`	string	Two-letter continent code, e.g. `"EU"`.
`continent`	string	Continent name.
`proxy`	boolean	`true` when the address is a VPN, proxy, Tor exit, hosting or compromised address.
`type`	string	The connection type. See connection types.

Connection types

Both versions return one of these values in type. When more than one applies, the first match in this order wins.

Value	`proxy`	Meaning
Tor Exit	`true`	A Tor network exit node.
VPN	`true`	A commercial or self-hosted VPN endpoint.
Hosting	`true`	A datacenter or cloud provider address.
Residential Proxy	`true`	A home connection that has been seen relaying traffic for others.
Proxy	`true`	An open or commercial proxy.
Residential	`false`	An ordinary connection with nothing detected.

Errors & special cases

Most problems still return 200 with a recognisable body, so check the body rather than the status code alone.

Missing ip 400: {"error":"Missing ip parameter"}
Invalid address 200: Every field is set to "Invalid IP".

{"ip":"Invalid IP","proxy":"Invalid IP","type":"Invalid IP"}
Rate limited 200: Every field is set to "API Rate Limited". Wait, then retry.

{"ip":"API Rate Limited","proxy":"API Rate Limited","type":"API Rate Limited"}
Private or reserved range 200: Addresses such as 10.0.0.0/8, 192.168.0.0/16, loopback and link-local aren't routable on the internet, so they have no data.

{"ip":"10.0.0.1","bogon":true}
No data available 200: The upstream lookup failed or had nothing on record. Only ip comes back.

{"ip":"203.0.113.7"}

The invalid and rate-limited examples are shortened; the real response repeats the value in every field of that version.

Need more?

Batch lookups or higher limits for your project? Get in touch and tell us what you're building.

support@cotoax.com