Beeping Beeping

API Documentation

About this API

Beeping is a RESTful API designed with simplicity in mind. Every endpoint serves both HTML (for humans) and JSON (for machines) depending on the Accept header you send.

There's no separate /api prefix — the same URLs work for both browser visits and API calls. This keeps the architecture clean and predictable.

This service is free and open for everyone to use. However, please be respectful: avoid excessive request rates that could impact service availability for others. If you need high-volume access, consider caching responses or reach out to discuss options.

💡 How to use the API

For JSON responses: Add the header Accept: application/json

For HTML pages: Use Accept: text/html or just visit the URL in your browser

For terminal output: Nothing to add — it's the default for curl, wget and httpie. See below.

🖥️ Terminal output for CLI clients

Every tool endpoint also serves a third representation: plain text with ANSI colors, laid out for a terminal. It's the default for curl, wget and httpie — no headers needed: 

curl https://beeping.app/tools/ping/1.1.1.1

Force it explicitly with Accept: text/plain. Colors are on by default for curl/httpie; disable them with the X-No-Color header or ?color=0 (?color=1 forces them back on, e.g. when piping through less -R).

GET / always returns the bare IP by default (nothing changes there) — add ?full to opt into the same enriched terminal view (IP, location, network) as the other endpoints.

📑 Table of Contents

API Endpoints

Back to Menu

GET /

Detects client IP address and returns complete information including geolocation and ASN data.

Headers

  • Accept: application/json - Returns JSON response
  • Accept: text/html - Returns HTML page (default for browsers)

Query Parameters

  • ?full - Opt-in enriched terminal view (IP, location, network) for CLI clients. The default response is always the bare IP — see the terminal output section above.

Example Request

# Bare IP (curl/wget/httpie default, no headers needed)
curl https://beeping.app/

# JSON
curl -H "Accept: application/json" https://beeping.app/

# Enriched terminal view (opt-in)
curl https://beeping.app/?full

Example Response

{
  "ip": "64.81.161.249",
  "version": 4,
  "type": "global",
  "geo": {
    "country": {
      "code": "ES",
      "name": "Spain"
    },
    "city": "Madrid",
    "location": {
      "latitude": 40.4165,
      "longitude": -3.70256
    }
  },
  "asn": {
    "asn": 15704,
    "organization": "XTRA TELECOM S.A.",
    "network_type": "isp"
  }
}
Back to Menu

GET /tools/ip-analyzer/{ip}

Analyzes a specific IP address and returns detailed information about its properties and classification.

Parameters

  • ip - IPv4 or IPv6 address to analyze

Example Request

curl -H "Accept: application/json" https://beeping.app/tools/ip-analyzer/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "version": "IPv4",
  "is_ipv4": true,
  "is_ipv6": false,
  "is_loopback": false,
  "is_private": false,
  "is_global": true,
  "is_multicast": false,
  "is_broadcast": false,
  "is_documentation": false,
  "is_unspecified": false,
  "is_reserved": false,
  "ip_class": "A",
  "cidr_notation": "8.8.8.8/32",
  "default_mask": "255.0.0.0",
  "network_type": "Global (Public)"
}
Back to Menu

GET /tools/geo/lookup/{ip}

Looks up geographic information for a specific IP address including country, city, and location coordinates.

Parameters

  • ip - IPv4 or IPv6 address to lookup

Example Request

curl -H "Accept: application/json" https://beeping.app/tools/geo/lookup/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "geo": {
    "country": {
      "code": "US",
      "name": "United States"
    },
    "city": "Mountain View",
    "location": {
      "latitude": 37.419,
      "longitude": -122.057
    }
  }
}

Use Cases

  • Content localization based on visitor location
  • Security monitoring and fraud detection
  • Analytics and traffic analysis
  • Geographic access restrictions
Back to Menu

GET /tools/asn/lookup/{ip}

Looks up ASN information for a specific IP address including ASN number, organization and network type.

Parameters

  • ip - IPv4 or IPv6 address to lookup

Example Request

curl -H "Accept: application/json" https://beeping.app/tools/asn/lookup/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "asn": {
    "asn": 15169,
    "organization": "GOOGLE",
    "network_type": "hosting"
  }
}

Use Cases

  • Identify hosting providers vs ISPs
  • Security and threat attribution
  • Traffic analysis and routing decisions
Back to Menu

GET /tools/dns/lookup/{domain}

Performs DNS record lookup for a domain name.

Parameters

  • domain - Domain name to lookup (path parameter)

Query Parameters

  • record_type - Record type: A, AAAA, MX, TXT, CNAME, NS, SOA, PTR, CAA, SRV (optional, default: A)

Example Request

curl -H "Accept: application/json" "https://beeping.app/tools/dns/lookup/google.com?record_type=A"

Example Response

{
  "domain": "google.com",
  "record_type": "A",
  "records": [
    "142.250.179.110"
  ],
  "ttl": 300,
  "query_time_ms": 11
}
Back to Menu

GET /tools/dns/propagation/{domain}

Checks DNS propagation across 21 global DNS servers.

Parameters

  • domain - Domain name to check (path parameter)

Query Parameters

  • record_type - Record type: A, AAAA, MX, TXT, CNAME, NS, SOA, PTR, CAA, SRV (optional, default: A)

Example Request

curl -H "Accept: application/json" "https://beeping.app/tools/dns/propagation/google.com?record_type=A"

Example Response

[
  {
    "server": {
      "name": "Cloudflare",
      "location": "San Francisco, CA",
      "country": "USA",
      "ip": "1.1.1.1",
      "latitude": 37.775,
      "longitude": -122.419
    },
    "status": "propagated",
    "records": [
      "142.251.39.206"
    ],
    "error_message": null
  },
  {
    "server": {
      "name": "Google Public DNS",
      "location": "Mountain View, CA",
      "country": "USA",
      "ip": "8.8.8.8",
      "latitude": 37.419,
      "longitude": -122.057
    },
    "status": "propagated",
    "records": [
      "142.250.179.110"
    ],
    "error_message": null
  },
  {
    "server": {
      "name": "OpenDNS",
      "location": "San Jose, CA",
      "country": "USA",
      "ip": "208.67.222.222",
      "latitude": 37.339,
      "longitude": -121.895
    },
    "status": "error",
    "records": [],
    "error_message": "no record found for Query { name: Name(\"google.com.\"), query_type: A, query_class: IN }"
  }
]
Back to Menu

GET /tools/ping/{target}

Tests network connectivity and latency to a target IP address or hostname. Returns RTT statistics, packet loss, jitter, OS detection from TTL, and connection quality metrics.

Parameters

  • target - IP address or hostname to ping (path parameter)

Query Parameters

  • count - Number of ping attempts (1-10, default: 4)
  • method - Ping method: 'tcp' or 'http' (default: tcp)

Example Request

curl -H "Accept: application/json" "https://beeping.app/tools/ping/8.8.8.8?count=4&method=tcp"

Example Response

{
  "target": "8.8.8.8",
  "resolved_ip": "8.8.8.8",
  "method": "tcp",
  "packets_sent": 4,
  "packets_received": 4,
  "packet_loss_percent": 0.0,
  "rtt_min_ms": 12.34,
  "rtt_avg_ms": 14.56,
  "rtt_max_ms": 16.78,
  "jitter_ms": 1.23,
  "ttl": 58,
  "os_detection": {
    "likely_os": "Linux/Unix",
    "confidence": 0.85,
    "ttl_expected": 64,
    "ttl_hops": 6
  },
  "connection_quality": {
    "score": 94,
    "rating": "Excellent",
    "is_stable": true,
    "jitter_rating": "Excellent"
  },
  "geo_analysis": {
    "distance_km": null,
    "expected_latency_ms": null,
    "latency_anomaly": false,
    "anomaly_score": 1.0
  },
  "timestamp": "2025-11-21T10:30:00Z"
}

Response Fields

  • rtt_min/avg/max_ms - Round-trip time statistics in milliseconds
  • jitter_ms - Average latency variation between pings
  • ttl - Time-To-Live value observed (used for OS detection)
  • os_detection.likely_os - Detected operating system (Linux/Unix, Windows, Network Device)
  • os_detection.confidence - Detection confidence (0.0-1.0)
  • os_detection.ttl_hops - Estimated number of network hops
  • connection_quality.score - Overall quality score (0-100)
  • connection_quality.rating - Excellent, Good, Fair, or Poor
  • geo_analysis.latency_anomaly - True if latency is unexpectedly high for distance

Notes

  • TCP method connects to port 80 or 443 (HTTPS fallback)
  • HTTP method sends a HEAD request to the target
  • TTL-based OS detection is heuristic and may not be 100% accurate
  • Jitter <5ms is excellent, 5-15ms is good, 15-30ms is fair, >30ms is poor
  • Quality score considers latency, jitter, and packet loss
  • Without Accept: application/json, curl/wget/httpie get the ANSI terminal representation shown in the intro instead of this JSON
Back to Menu

GET /tools/subnet/{cidr}

Calculates subnet information from CIDR notation including network address, broadcast address, subnet mask, wildcard mask, and usable host range.

Parameters

  • cidr - IP address with prefix length (e.g., 192.168.1.0/24)

Example Request

curl -H "Accept: application/json" https://beeping.app/tools/subnet/192.168.1.0/24

Example Response

{
  "input": "192.168.1.0/24",
  "ip_address": "192.168.1.0",
  "network_address": "192.168.1.0",
  "broadcast_address": "192.168.1.255",
  "subnet_mask": "255.255.255.0",
  "wildcard_mask": "0.0.0.255",
  "cidr_notation": "192.168.1.0/24",
  "prefix_length": 24,
  "total_hosts": 256,
  "usable_hosts": 254,
  "first_usable": "192.168.1.1",
  "last_usable": "192.168.1.254",
  "ip_class": "C",
  "is_private": true
}

Use Cases

  • Network planning and subnetting
  • Firewall rule configuration
  • IP address range allocation
  • Network documentation
Back to Menu

GET /tools/traceroute/{target}

Traces the network path to a target IP address or hostname. Discovers all routers (hops) between the server and the destination, measuring latency at each step.

Parameters

  • target - IP address or hostname to trace (path parameter)

Query Parameters

  • max_hops - Maximum number of hops to trace (1-64, default: 30, optional)
  • probes_per_hop - Number of probes to send per hop (1-10, default: 3, optional)
  • timeout_ms - Timeout per probe in milliseconds (100-30000, default: 5000, optional)

Example Request

# Basic request with defaults
curl -H "Accept: application/json" "https://beeping.app/tools/traceroute/8.8.8.8"

# Custom parameters
curl -H "Accept: application/json" "https://beeping.app/tools/traceroute/google.com?max_hops=20&probes_per_hop=5&timeout_ms=3000"

Example Response

{
  "target": "8.8.8.8",
  "resolved_ip": "8.8.8.8",
  "hops": [
    {
      "hop": 1,
      "ip": "192.168.1.1",
      "hostname": "router.local",
      "probes": [
        {"rtt_ms": 1.234, "responder_ip": "192.168.1.1"},
        {"rtt_ms": 1.156, "responder_ip": "192.168.1.1"},
        {"rtt_ms": 1.298, "responder_ip": "192.168.1.1"}
      ],
      "avg_rtt_ms": 1.229,
      "min_rtt_ms": 1.156,
      "max_rtt_ms": 1.298,
      "rtt_bar_width": 0,
      "is_destination": false
    },
    {
      "hop": 2,
      "ip": "10.0.0.1",
      "hostname": "isp-gateway.example.com",
      "probes": [
        {"rtt_ms": 15.432, "responder_ip": "10.0.0.1"},
        {"rtt_ms": 15.678, "responder_ip": "10.0.0.1"},
        {"rtt_ms": 15.234, "responder_ip": "10.0.0.1"}
      ],
      "avg_rtt_ms": 15.448,
      "min_rtt_ms": 15.234,
      "max_rtt_ms": 15.678,
      "rtt_bar_width": 7,
      "is_destination": false,
      "country_code": "FR",
      "network": "AS12876 Scaleway",
      "city": "Paris",
      "location": {"latitude": 48.8566, "longitude": 2.3522}
    },
    {
      "hop": 3,
      "ip": null,
      "hostname": null,
      "probes": [
        {"rtt_ms": null, "responder_ip": null},
        {"rtt_ms": null, "responder_ip": null},
        {"rtt_ms": null, "responder_ip": null}
      ],
      "avg_rtt_ms": null,
      "min_rtt_ms": null,
      "max_rtt_ms": null,
      "rtt_bar_width": 0,
      "is_destination": false
    }
  ],
  "destination_reached": false,
  "total_hops": null,
  "responsive_hops": 2,
  "timeout_hops": 1,
  "timestamp": 1700000000000,
  "summary": {
    "hops": 3,
    "countries": 1,
    "networks": 1,
    "country_path": ["FR"]
  }
}

Response Fields

  • hops - Array of network hops from source to destination
  • hop - Hop number (TTL value used)
  • ip - IP address of the router at this hop (null if timeout)
  • hostname - Reverse DNS hostname of the router (if available)
  • probes - Results from 3 probe attempts per hop
  • avg_rtt_ms - Average round-trip time for successful probes
  • country_code - ISO 3166-1 alpha-2 country code of the responding IP (public IPs with geo data only)
  • network - ASN and organization of the responding IP, e.g. "AS12876 Scaleway" (public IPs with ASN data only)
  • city - City name of the responding IP (public IPs with geo data only)
  • location - {latitude, longitude} of the responding IP (public IPs with geo data only)
  • destination_reached - Whether the target destination was reached
  • total_hops - Number of hops to destination (if reached)
  • responsive_hops - Count of hops that responded
  • timeout_hops - Count of hops that timed out
  • summary - Aggregated route view: hops, countries, networks, total_rtt_ms (destination RTT, if reached), country_path (country codes in route order, consecutive duplicates collapsed)

Notes

  • Uses ICMP packets with incrementing TTL values to discover routes
  • Some routers may not respond to traceroute probes (shown as null/timeout)
  • Traceroute stops after 3 consecutive timeouts or reaching max_hops
  • Reverse DNS lookups are performed asynchronously for each hop
  • Default values can be configured via environment variables (BEEPING_TRACEROUTE_*)
  • Query parameters override server defaults if provided
  • All parameters are validated and clamped to safe limits
  • Requires CAP_NET_RAW capability on the server
  • Without Accept: application/json, curl/wget/httpie get the ANSI terminal representation shown in the intro instead of this JSON — including country and ASN per hop
  • Router geolocation is approximate: country_code, city and location only appear for public IPs with an entry in the geo database, and often resolve to the operator's registered location or a country centroid rather than the router's physical position

Use Cases

  • Network troubleshooting and path analysis
  • Identifying routing issues or bottlenecks
  • Measuring per-hop latency increases
  • Detecting network topology changes
  • Analyzing CDN or anycast routing
Back to Menu

GET /tools/dns/reverse/{ip}

Performs reverse DNS lookup (PTR record) for an IP address.

Parameters

  • ip - IPv4 or IPv6 address to lookup

Example Request

curl -H "Accept: application/json" https://beeping.app/tools/dns/reverse/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "ptr_records": [
    "dns.google"
  ],
  "lookup_time_ms": 8,
  "success": true,
  "error": null,
  "forward_verified": true
}
Back to Menu

GET /tools/leak-test

Detects WebRTC, IPv6 and DNS leaks in a VPN connection. The checks run in the browser (WebRTC, timezone) and on the server (exit IP, ASN, DNS resolver), tied together by a token that lives 120 seconds in memory — nothing is persisted to disk.

Token flow

  1. GET /tools/leak-test creates a token and returns the page (or JSON/text explaining you need a browser).
  2. The page's JS runs the WebRTC and timezone checks, then POSTs its findings for that token.
  3. GET /tools/leak-test/{token} returns the server-computed report combining client findings, the exit IP's ASN, and (when configured) observed dual-stack IPs and DNS resolvers.

Endpoints

  • GET /tools/leak-test - create a token and get the page (JSON/text/HTML)
  • GET /tools/leak-test/{token} - the leak report for that token (JSON/text/HTML)
  • POST /tools/leak-test/{token} - upload client-side findings (JSON body, JSON response)
  • GET /tools/leak-test/{token}/observe - records the IP the server sees for this token; used internally by the page to probe each IP stack via v4./v6. subdomains

Example Request

# Create a token
curl -H "Accept: application/json" https://beeping.app/tools/leak-test

# Read the report for that token (open the page in a browser instead to run the checks)
curl -H "Accept: application/json" https://beeping.app/tools/leak-test/<token>

Example Response

{
  "token": "0123456789abcdef0123456789abcdef",
  "exit_ip": "203.0.113.7",
  "exit_country": "NL",
  "exit_network": "AS0000 EXAMPLE-HOSTING",
  "checks": [
    { "kind": "webrtc", "status": "ok", "detail": "no candidates exposed" },
    { "kind": "ipv6", "status": "skipped", "detail": "dual-stack check not configured or not reachable" },
    { "kind": "timezone", "status": "info", "detail": "browser timezone (Europe/Madrid) does not match exit country (NL) — consistent with an active VPN" },
    { "kind": "vpn_asn", "status": "info", "detail": "your exit IP belongs to a hosting/datacenter network (EXAMPLE-HOSTING) — consistent with a VPN or proxy" },
    { "kind": "dns", "status": "skipped", "detail": "DNS leak zone not configured" }
  ],
  "verdict": "no_leaks"
}
Back to Menu

GET /health

Health check endpoint for monitoring service status. Returns plain text "OK".

Example Request

curl https://beeping.app/health

Example Response

OK
Back to Menu

GET /stats

Returns service statistics and metrics.

Headers

  • Accept: application/json - Returns JSON response
  • Accept: text/html - Returns HTML page (default)

Example Request

curl -H "Accept: application/json" https://beeping.app/stats

Example Response

{
  "total_requests": 3592661,
  "ipv4_requests": 3586495,
  "ipv6_requests": 6166,
  "bot_requests": 3583784,
  "json_requests": 12,
  "html_requests": 8865,
  "health_checks": 10,
  "errors": 0,
  "tools": {
    "geo_lookup": 3,
    "ping": 2
  }
}
Back to Menu

Code Examples

JavaScript (fetch)

fetch('https://beeping.app/', {
    headers: { 'Accept': 'application/json' }
})
.then(response => response.json())
.then(data => console.log(data));

Python (requests)

import requests

response = requests.get(
    'https://beeping.app/',
    headers={'Accept': 'application/json'}
)
print(response.json())

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://beeping.app/", nil)
    req.Header.Set("Accept", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}