JSON API reference
The API is public and requires no API key. Send HTTPS GET requests; successful responses use application/json. Examples show response shapes and values can change.
OpenAPI specification (JSON)
GET /api/v1/me
Return the IP address and available edge-network details for the machine making this request.
Parameters: No query parameters.
Response fields
ip- Caller public IP address.
version- IPv4 or IPv6.
location- Approximate city/region/country, or null when unavailable.
network- Network organization, or null.
asn- Autonomous system number, or null.
country- Two-letter country code, or null.
latitude / longitude- Approximate coordinates, or null.
example- True only for the local preview sample.
Request example
curl https://myipgo.com/api/v1/me
Illustrative response
{
"ip": "203.0.113.42",
"version": "IPv4",
"location": "Amsterdam, Netherlands",
"network": "Example Network (AS64500)",
"asn": 64500,
"country": "NL",
"latitude": 52.37,
"longitude": 4.9,
"example": true
}
GET /api/v1/lookup
Return the validated IP version and, when provider data is configured and available, country and ASN details. City-level location is not returned.
Parameters: Required: ip — an IPv4 or IPv6 address.
Response fields
ip- The queried address.
version- IPv4 or IPv6.
source- Limited when only validation is available; IPinfo Lite when provider data is returned.
country- Country name, when available.
countryCode- Two-letter country code, when available.
continent- Continent name, when available.
continentCode- Two-letter continent code, when available.
network- Network/ASN organization name, when available.
asn- Autonomous system identifier, when available.
as_domain- Associated network domain name, when available.
Request example
curl --get https://myipgo.com/api/v1/lookup --data-urlencode ip=1.1.1.1
Illustrative response
{
"ip": "1.1.1.1",
"version": "IPv4",
"source": "Limited"
}
When IPinfo Lite is configured, the response also includes country, countryCode, continent, continentCode, network, asn, and as_domain. Missing provider data does not imply that the address has no country or network.
GET /api/v1/dns
Query a DNS record and return the resolver response code plus up to 30 answer records.
Parameters: Required: name — DNS name up to 253 characters; allowed characters are ASCII letters, digits, dot, underscore, and hyphen. Use Punycode for internationalized names. Optional: type — A, AAAA, CNAME, MX, NS, TXT, SOA, or PTR; defaults to A.
Response fields
query- Name sent to the DNS resolver.
type- Requested record type.
status- DNS response code from the resolver; 0 means NOERROR and 3 means NXDOMAIN. A DNS error code can still arrive in HTTP 200.
records- Answer records; empty when the response has no answers.
records[].type- Record type.
records[].value- Record data as text.
records[].ttl- Time to live in seconds.
Request example
curl --get https://myipgo.com/api/v1/dns --data-urlencode name=example.com --data-urlencode type=A
Illustrative response
{
"query": "example.com",
"type": "A",
"status": 0,
"records": [
{ "type": "A", "value": "192.0.2.1", "ttl": 300 }
]
}
The response sample uses a documentation-only IP address. A valid DNS lookup with no matching records is still an HTTP 200 response with an empty records array and the resolver status.
GET /api/v1/reverse
Create the reverse-mapping name for an IPv4 or IPv6 address and query its PTR records.
Parameters: Required: ip — an IPv4 or IPv6 address.
Response fields
query- Generated in-addr.arpa (IPv4) or ip6.arpa (IPv6) name.
type- PTR.
status- DNS response code; 0 means NOERROR and 3 means NXDOMAIN.
records- Up to 30 PTR answers with type, value, and ttl.
Request example
curl --get https://myipgo.com/api/v1/reverse --data-urlencode ip=1.1.1.1
Illustrative response
{
"query": "1.1.1.1.in-addr.arpa",
"type": "PTR",
"status": 0,
"records": [
{ "type": "PTR", "value": "one.one.one.one", "ttl": 300 }
]
}
Response values and TTL vary with DNS data. The query field is the generated reverse name, not the original IP.
Command-line IP
Use this from a terminal to print only the address of the machine making the request. The root URL returns plain text to common command-line clients; browsers continue to receive the website. Use /ip for an explicit plain-text endpoint.
curl -fsS https://myipgo.com
curl -fsS https://myipgo.com/ip
curl -fsS https://myipgo.com/json
curl -fsS https://myipgo.com/asn
curl -fsS https://myipgo.com/country
curl -fsS https://myipgo.com/city
npx myipgo
HTTP errors
Errors use JSON with an error string. A DNS negative answer is different: it is returned as HTTP 200 with a non-zero DNS status.
400Invalid inputInvalid IP address, Invalid DNS query, or invalid IPv4 CIDR/prefix.
403Origin not allowedMCP request Origin does not match the request host.
404Unknown endpointNo matching /api/v1 endpoint.
405Method not allowedJSON API requires GET; MCP requires POST.
503Upstream unavailableResolver unavailable or IP data provider unavailable; retry later.
{ "error": "Invalid IP address" }
No numeric request quota is published. Use reasonable request rates and avoid tight polling loops.
MCP over Streamable HTTP
Connect an MCP client to https://myipgo.com/mcp using Streamable HTTP. No API key is required. The endpoint is stateless; use a current MCP client SDK to handle protocol initialization and message framing.
Available tools
my_ip- No arguments. Returns the caller server IP and available approximate edge details.
lookup_ip- ip (string, required). Looks up country/network/domain data when available; never returns city-level data.
dns_lookup- name (string, required); type (A, AAAA, CNAME, MX, NS, TXT, or SOA; optional, defaults to A).
reverse_dns- ip (string, required). Looks up PTR records for an IPv4 or IPv6 address.
subnet_calculator- cidr (string, required). Calculates an IPv4 CIDR network; prefixes 0–32 are supported. Returns network, broadcast (null for /31 and /32), usable host range, netmask, wildcard mask, and address counts.
Node.js client example
npm install @modelcontextprotocol/sdk
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'myipgo-client', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(
new URL('https://myipgo.com/mcp')
));
const result = await client.callTool({
name: 'subnet_calculator',
arguments: { cidr: '192.168.1.0/24' }
});
if (result.isError) throw new Error(result.content[0]?.text);
console.log(result.structuredContent ?? result.content);
await client.close();
Successful tools return a JSON text content item and structuredContent. Tool failures return isError: true and a text message; protocol/transport failures are separate.