MyIP.dogStart with one IP address API request
The IP address API answers a narrow question: which public address did this endpoint observe for this request? It supports connection diagnostics, a user-triggered support check, or a small command-line script. It does not identify a person, inspect every network interface, locate a device precisely, or accept another address for investigation.
Choose /ip when your IP address API integration needs one line of text. Choose /api/v1/ip when you need JSON containing the address, its family, the observation source and a timestamp. Both use the same trusted request context. Neither requires an account, API key, request body or query parameter.
curl --fail --silent --show-error --max-time 8 https://myip.dog/ip
The command fails on an HTTP error instead of treating an error message as an address. Its total timeout is eight seconds. Check the exit status before using the output in another command. The IP address API must remain a diagnostic input, rather than an unconditional dependency for opening your application.
For structured output, change the path in that IP address API command:
curl --fail --silent --show-error --max-time 8 https://myip.dog/api/v1/ip
These IP address API examples target the intended production origin. A local preview uses its own origin, and a loopback request normally cannot establish a public caller address. The live control above tests the origin currently serving this page. A successful local build does not prove public deployment or IPv6 reachability.
What the IP address API caller means
Run the IP address API request in the environment you want to investigate. A browser request observes that browser's exit path. A request from a backend observes the backend's connection. Calling it from your server and displaying the result as a visitor's address would answer the wrong question.
A VPN, HTTP proxy, shared gateway or privacy relay can change what an IP address API observes. Several people may share the same exit address. One person may use multiple addresses. Never use the result as an authentication credential, a permanent account identifier, or proof that a connection has no leaks.
Read the IP address API response contract
The following JSON illustrates the IP address API shape. 203.0.113.10 is a documentation address, and the timestamp is an example. Neither is a live observation. Actual successful responses contain an observed public address; unavailable observations produce an error instead of a sample or an empty success.
{
"code": 0,
"message": "ok",
"data": {
"ip": "203.0.113.10",
"version": 4,
"source": "cloudflare",
"observedAt": "2026-09-28T00:00:00.000Z"
}
}
The IP address API uses an envelope: code is 0 for success and -1 for a handled error. Successful responses include data; handled errors include a readable message and omit data. Check both HTTP status and the success code. Treat messages as explanations, not stable machine identifiers.
Within the IP address API data object, ip is a string in normalized notation. version is the number 4 or 6, not a string. observedAt is an ISO timestamp for the request observation. Preserve IPv6 strings intact; splitting every address on a colon is not a valid parser.
The IP address API source is cloudflare when the supported edge request provides trusted visitor information, or direct when the runtime supplies a usable direct peer. Arbitrary incoming X-Forwarded-For or CF-Connecting-IP headers cannot establish trust by themselves. An unsupported proxy setup can fail to identify the original caller.
The /ip variant returns only the normalized address followed by a newline on success. It returns a readable error line with a non-success status on failure. Your IP address API parser should require success before trimming the newline and validating the address. Do not extract numbers from an error body.
The downloadable OpenAPI contract describes both formats and their response schemas. An IP address API client should tolerate additional object fields while validating the fields it consumes. The JSON path contains a major version. This document does not promise a deprecation notice period, service-level agreement or unlimited availability.
Call the IP address API from a browser
A browser integration can call the public IP address API without credentials. Trigger the request when its result is useful to the user. Avoid running a new request during every render, animation, keystroke or background timer. A support panel often needs only one deliberate observation and a clearly labelled refresh.
async function observePublicIp() {
const response = await fetch('https://myip.dog/api/v1/ip', {
credentials: 'omit',
cache: 'no-store',
signal: AbortSignal.timeout(8000),
});
if (!response.ok) {
throw new Error(`Address check failed: HTTP ${response.status}`);
}
const result = await response.json();
if (
result.code !== 0 ||
typeof result.data?.ip !== 'string' ||
![4, 6].includes(result.data?.version)
) {
throw new Error('Unexpected address response');
}
return result.data;
}
This small IP address API example shows the transport and envelope checks. Applications should also validate addresses using a maintained parser, handle cancellation and show a useful failure state. Catch the rejected promise where the user action is handled. Older environments may need an AbortController-based timeout implementation.
The public IP address API sets Access-Control-Allow-Origin: * and supports GET, HEAD and OPTIONS. Send no authentication header, cookie requirement or custom request headers. OPTIONS returns an empty 204 response; it describes supported methods and does not measure a connection or consume the observation limit.
Wildcard CORS does not permit a credentialed cross-origin browser response. The IP address API exposes Retry-After so browser callers can read the wait time when present. A browser-blocked request may appear as a network error, even when no readable HTTP response is available. Inspect developer tools before guessing the cause.
If your application has a service worker, exclude the personalized IP address API response from shared caches. The endpoint sends private, no-store headers, including CDN-specific controls. A reverse proxy or custom cache must preserve that intent. Showing one visitor another visitor's stored observation would be a serious implementation error.
Handle IP address API limits and failures
The IP address API has a runtime-local burst guard: sixty successful GET or HEAD observations per trusted address during a fixed sixty-second window. JSON and text requests share this counter. The first observation starts the window. A denied request receives HTTP 429 and a Retry-After duration in seconds.
That IP address API guard is not a globally coordinated account quota. A distributed deployment may have multiple runtime instances, and edge protection may impose additional restrictions. People sharing a public gateway can share a bucket. Do not interpret the local limit as a guaranteed allowance, throughput promise or permission to poll continuously.
Handle the IP address API statuses according to what actually failed:
- 200: the request produced a public observation, or HEAD confirmed that status without a body.
- 400: query parameters were supplied. Remove them; arbitrary IP inputs, JSONP callbacks and format parameters are unsupported.
- 405: the method is unsupported. Use GET or HEAD; OPTIONS is available for method discovery.
- 429: the observation bucket is exhausted. Respect
Retry-Afterbefore another attempt. - 503: a trusted public observation is unavailable, or the runtime cannot allocate another active bucket. Capacity errors include a retry hint.
Other infrastructure layers can fail before the IP address API produces its normal envelope. Your client must handle timeouts, DNS failures, TLS problems and non-JSON error pages. Keep the interface usable. An unavailable observation is not evidence that the user has no address or that a VPN is safe.
Retry an IP address API request only when the failure could be temporary. Use a small attempt budget, increasing waits and random jitter; honor a longer server hint. Do not immediately retry a malformed request. Avoid multiple independent retry loops in a component, a query library and a service worker.
HEAD provides IP address API status and headers without an address body. It uses the same observation checks and counts toward the same burst limit when successful. It is useful for a bounded diagnostic, not a free unlimited health probe. A localhost HEAD can correctly return 503 despite the application running normally.
Interpret IPv4 and IPv6 correctly
An IP address API response describes the family used for that observation. Seeing IPv4 does not prove that IPv6 is unavailable. Seeing IPv6 does not enumerate every IPv6 address on the device. Network selection, proxies, DNS answers and application preferences can affect which path reaches the endpoint.
For a direct IP address API comparison, curl can request a particular destination family:
curl -4 --fail --silent --show-error --max-time 8 https://myip.dog/ip
curl -6 --fail --silent --show-error --max-time 8 https://myip.dog/ip
These IP address API commands require corresponding DNS records and a usable route in the deployment being tested. A failed forced-family request needs investigation; it is not automatically proof of a client network defect. Proxies may also affect family selection. No dedicated IPv4-only or IPv6-only hostname is promised here.
Use the IPv6 test for separately labelled browser probes, and read IPv6 address format before processing compressed notation. The IP address API reports one observation and does not silently call an external address service when the request context is missing. That keeps the source boundary explicit.
IP address API privacy, storage and trust
Minimize how much IP address API output your application retains. A support ticket may need a time-limited observation; analytics usually do not need raw addresses embedded in event names, page paths or custom properties. Explain the purpose to users, restrict access and choose retention based on that actual purpose.
The IP address API does not require an application account or write observations to the product database. Its burst guard temporarily holds addresses in process memory; expired entries can remain until cleanup or runtime exit. Hosting, edge protection and network providers may maintain their own logs. This is not a zero-logging promise.
Do not append account identifiers, secrets or diagnostic payloads to an IP address API URL. Query parameters are rejected, and URLs can still pass through infrastructure logs before rejection. HTTPS protects the connection in transit but does not remove every downstream retention risk. Share copied observations deliberately rather than automatically.
Verify an IP address API integration before release
Test an IP address API integration in the browser, terminal or backend environment where it will run. Confirm that the displayed source and family match the question you asked. Compare observations after a deliberate network change, and keep their timestamps. A stale successful result must not silently become the current result.
Exercise IP address API success, non-success HTTP responses, malformed bodies, cancellation and a slow connection. Check that your loading state ends, copy controls copy the intended payload, and old results are cleared or labelled. Use deterministic fixtures for error paths rather than exhausting a public service just to test retries.
Before deploying behind a proxy, verify the actual client-address handoff and ensure the IP address API response is never shared between visitors. Test two independent connections and inspect cache headers. Check public DNS and TLS separately from application tests. A passing unit test cannot establish the behavior of an unconfigured hosting boundary.
For human-readable investigation, use IP lookup, IP testing methodology and data sources. They explain registration, observation and provider limitations beyond this IP address API contract. Use the home page when someone simply needs a visible, copyable public address without writing an integration.
IP address API references and verification scope
The endpoint descriptions come from the implementation and its contract tests. Supporting references are the curl manual, MDN CORS guide, MDN timeout API, Cloudflare request-header reference and OpenAPI 3.1 specification. Sources were checked on September 28, 2026. These references explain platform behavior; they do not certify this site's deployment, uptime or performance.