Developer API and local collector
A versioned v1 contract, per-key usage and egress monitoring running on your own computer.
Updated · Egress Observatory
Request contract
The prefix is /myip-api/v1. Pass a key in Authorization: Bearer; never put it in URLs, public scripts or browser storage. Responses prohibit caching and indexing.
Successful responses contain apiVersion, observedAt and data. observedAt is the API read time; snapshot timestamps are in data.datasets. Invalid input returns 400, invalid credentials 401, exceeded quotas 429, and unavailable configuration or data 503. Preserve unknown states rather than converting them into zero risk.
Each key is limited to 60 requests per minute; operators configure UTC daily quotas. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset describe usage. On 429, respect Retry-After and back off. This version reads local snapshots without querying commercial reputation sources.
For 429 responses, usage.limitType distinguishes minute and daily limits. usage.retryAt is the actual UTC recovery timestamp in milliseconds; retryAfterSeconds and Retry-After give the remaining seconds. Minute limits reset at the next UTC minute and daily limits at UTC midnight. If both are exhausted, wait for the daily reset. /usage does not consume daily quota but still counts toward the minute limit.
data.fieldEvidence.asn/country records the source, dataset, snapshot version, queriedAt (query time), and downloadedAt (download time) used for each field. Missing source records remain null. Query time is not the database update time.
- GET /ip/{ip}
- Public IPv4/IPv6 classification from local snapshots, including source freshness.
- GET /sources
- Local source status, snapshot times and freshness policy.
- GET /usage
- Current-key UTC daily usage and reset time, without consuming quota.
- GET /schema
- Public API contract and real integration status; no key required.
curl -sS -H "Authorization: Bearer $IP_INSPECTOR_KEY" "https://ip.oocore.com/myip-api/v1/ip/1.1.1.1"Local monitoring and command line
The collector is included in the source at cli/ip-inspector.mjs. It samples dual-stack egress every 60 seconds by default. An optional API key adds local ASN and country data. --dns queries a randomized authoritative name through the system resolver and requires configured delegation. HTTP and system DNS can use different routes.
To use HTTP_PROXY / HTTPS_PROXY, explicitly pass Node --use-env-proxy. Results describe this process route only; compare it with the browser first. The collector does not install services or schedule tasks automatically. Change notices appear only in the local terminal.
SQLite files and exports contain full IP addresses, use permissions 0600 by default, and retain at most 7 days or 10,080 samples. Import JSON on the monitoring page to inspect the timeline, time windows and sampling gaps.
When API quota is exhausted, the collector reports the recovery time and pauses ASN/country enrichment while dual-stack egress sampling continues. Cached metadata retains its original query time. Once expired, fields remain unknown or use the explicitly identified trace-country source. Monitoring separates egress IP changes from metadata changes; a database change does not establish a route change.
node cli/ip-inspector.mjs schema
# Set IP_INSPECTOR_KEY privately when using authenticated commands.
node cli/ip-inspector.mjs ip 1.1.1.1
node cli/ip-inspector.mjs usage
# Run on the computer whose egress matters. Ctrl+C stops collection.
node cli/ip-inspector.mjs monitor --db ./private/monitor.sqlite --hours 24
node cli/ip-inspector.mjs export --db ./private/monitor.sqlite --out ./private/monitor.jsonSelf-hosted configuration
Operators configure a persistent WORKBENCH_STATE_PATH, generate a separate key file with keygen, and add its serverKey to DEVELOPER_API_KEYS. The server stores SHA-256 digests only. Change or remove configuration to rotate or revoke keys. Corrections administrators use a separate CORRECTIONS_ADMIN_KEY.
There is no self-service registration or paid activation. Compatibility applies to the current v1 contract: fields can be added compatibly, while breaking changes require another version.
node cli/ip-inspector.mjs keygen --out ./private/api-key.json