Fix typos and enhance README content

Auto-detect Client IP:
The API now supports requests without the ip query parameter.
When this parameter is missing, the backend automatically detects and uses the requesting client’s IP address.
This enables quick ASN lookups for the caller’s own address without any client-side logic.

Updated Documentation:
The API documentation explains this behavior, showing example requests and the resulting JSON.
The Mermaid flowchart clearly visualizes the updated logic:

If ip is provided, use it.

Otherwise, seamlessly fall back to the real client IP.

User-Friendly Experience:
This change improves ease-of-use for web tools, scripts, and interactive diagnostics, allowing users to retrieve ASN info for their public IP in one step, with no parameters needed.

Backward Compatibility:
All existing query and locale options work as before, ensuring compatibility for integrators.

Consistency & Reliability:
The automatic fallback only picks up the genuine client address, maintaining high reliability and transparency in ASN and provider results.
This commit is contained in:
Tizian Maxime Weigt
2025-09-18 11:16:51 +02:00
committed by GitHub
parent a9105e10d5
commit f0e11c3372
+27 -25
View File
@@ -1,47 +1,41 @@
# IP-to-ASN Lookup API (fast hehe) # IP-to-ASN Lookup API (fast hehe)
This API allows you to lookup the **ASN**, **country**, **country name**, and **provider name** for a given IPv4 or IPv6 address. This API uses an very Optimized Cache to have very fast response times. The API does Support Quic (http3) and http2 to deliver fast responses! ⚡
This API allows you to lookup the **ASN**, **country**, **country name**, and **provider name** for a given IPv4 or IPv6 address. This API uses an very Optimzed Cache to have very fast response times. The API does Support Quic (http3) and http2 to deliver fast responses! ⚡ **Auto-detection feature:** If no IP parameter is provided, the API automatically uses the client's IP address from the request.
## Base URL ## Base URL
``` ```
https://cdn.t-w.dev/whois?ip={IP}&locale={locale} https://cdn.t-w.dev/whois?ip={IP}&locale={locale}
``` ```
* `ip` (optional) IPv4 or IPv6 address to query. If omitted, uses client IP
* `locale` (optional) `de`, `en`, or `both` (default: `both`) * `locale` (optional) `de`, `en`, or `both` (default: `both`)
--- ***
## Request ## Request
### Method ### Method
* **GET** or **POST** * **GET** or **POST**
### Parameters ### Parameters
| Name | Type | Required | Description | | Name | Type | Required | Description |
| ------ | ------ | -------- | ----------------------------------------------- | | ------ | ------ | -------- | ----------------------------------------------- |
| ip | string | Yes | IPv4 or IPv6 address to query | | ip | string | No | IPv4 or IPv6 address to query. If omitted, automatically uses the client's IP address |
| locale | string | No | Language for `country_name`: `de`, `en`, `both` | | locale | string | No | Language for `country_name`: `de`, `en`, `both` |
--- ***
## Response ## Response
### Success (200) ### Success (200)
| Field | Type | Description | | Field | Type | Description |
| ------------- | ------ | ----------------------------------------- | | ------------- | ------ | ----------------------------------------- |
| ip | string | The queried IP address | | ip | string | The queried IP address (provided or auto-detected) |
| asn | string | Autonomous System Number | | asn | string | Autonomous System Number |
| country | string | 2-letter country code of the ASN | | country | string | 2-letter country code of the ASN |
| country\_name | string | Localized country name (`locale` applied) | | country_name | string | Localized country name (`locale` applied) |
| description | string | Cleaned provider name (normalized) | | description | string | Cleaned provider name (normalized) |
| logo | string | Provider logo (not all) | | logo | string | Provider logo (not all) |
**Example:** **Example with specified IP:**
```json ```json
{ {
"ip": "8.8.8.8", "ip": "8.8.8.8",
@@ -53,37 +47,45 @@ https://cdn.t-w.dev/whois?ip={IP}&locale={locale}
} }
``` ```
### Error (400+) **Example using client IP (no ip parameter):**
```bash
curl https://cdn.t-w.dev/whois
```
```json
{
"ip": "203.0.113.45",
"asn": "64512",
"country": "DE",
"country_name": "Germany / Deutschland",
"description": "Example ISP",
"logo": null
}
```
### Error (400+)
| Field | Type | Description | | Field | Type | Description |
| ----- | ------ | -------------------------- | | ----- | ------ | -------------------------- |
| error | string | Description of the problem | | error | string | Description of the problem |
**Possible errors:** **Possible errors:**
```json
{ "error": "Missing 'ip' parameter" }
```
```json ```json
{ "error": "Invalid IP address" } { "error": "Invalid IP address" }
``` ```
```json ```json
{ "error": "ASN not found for given IP" } { "error": "ASN not found for given IP" }
``` ```
--- ***
## API Flow ## API Flow
```mermaid ```mermaid
flowchart TD flowchart TD
A[Client Request] --> B{IP parameter provided?} A[Client Request] --> B{IP parameter provided?}
B -- No --> C[Return Error: Missing 'ip' parameter] B -- No --> F2[Use Client IP from Request]
B -- Yes --> D{IP valid?} B -- Yes --> D{IP valid?}
D -- No --> E[Return Error: Invalid IP address] D -- No --> E[Return Error: Invalid IP address]
D -- Yes --> F[Lookup IP in ASN database] D -- Yes --> F[Lookup IP in ASN database]
F2 --> F
F --> G{ASN found?} F --> G{ASN found?}
G -- Yes --> H[Return JSON with ip, asn, country, country_name, description, logo] G -- Yes --> H[Return JSON with ip, asn, country, country_name, description, logo]
G -- No --> I[Return Error: ASN not found] G -- No --> I[Return Error: ASN not found]