WHOIS
Section: API Solutions
WHOIS lookup APIs (live, historical, reverse, bulk)
4 endpoints. Requests need your API key unless noted otherwise. See Authentication.
Live WHOIS Lookup
GET https://api.whoisfreaks.com/v2.0/whois/live
Real-time WHOIS lookup from authoritative servers. Cost 1 credit.
Parameters
| Parameter |
In |
Required |
Type |
Default |
Description |
domainName |
query |
yes |
string |
|
|
format |
query |
no |
string |
json |
(one of: json, xml) |
Response (WhoisResponse)
| Field |
Type |
Description |
status |
boolean |
|
domain_name |
string |
|
query_time |
string |
|
whois_server |
string |
|
domain_registered |
string |
|
secure_dns |
boolean |
|
domain_handle |
string |
|
create_date |
string |
|
update_date |
string |
|
expiry_date |
string |
|
domain_registrar |
RegistrarInformation |
|
reseller_contact |
ResellerContact |
|
registrant_contact |
PersonalInformation |
|
administrative_contact |
PersonalInformation |
|
technical_contact |
PersonalInformation |
|
billing_contact |
PersonalInformation |
|
eligibility_info |
EligibilityInfo |
|
abuse_contact |
RegistrarInformation |
|
name_servers |
array |
|
domain_status |
array |
|
whois_raw_domain |
string |
|
registry_data |
RegistryData |
|
RegistrarInformation object
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | |
| `id_type` | string | |
| `iana_id` | string | |
| `registry_id` | string | |
| `handle` | string | |
| `status` | string | |
| `registrar_name` | string | |
| `normalized_name` | string | |
| `whois_server` | string | |
| `rdap_server` | string | |
| `website_url` | string | |
| `email_address` | string | |
| `phone_number` | string | |
| `authoritative_registry_name` | string | |
| `organization_number` | string | |
| `is_sponsor` | boolean | |
ResellerContact object
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | |
| `email_address` | string | |
| `phone` | string | |
PersonalInformation object
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | |
| `id_type` | string | |
| `handle` | string | |
| `name` | string | |
| `company` | string | |
| `street` | string | |
| `city` | string | |
| `state` | string | |
| `zip_code` | string | |
| `country_name` | string | |
| `country_code` | string | |
| `email_address` | string | |
| `phone` | string | |
| `fax` | string | |
| `mailing_address` | string | |
EligibilityInfo object
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | |
| `name` | string | |
| `type` | string | |
RegistryData object
| Field | Type | Description |
|-------|------|-------------|
| `domain_name` | string | |
| `query_time` | string | |
| `whois_server` | string | |
| `domain_registered` | string | |
| `create_date` | string | |
| `update_date` | string | |
| `expiry_date` | string | |
| `domain_registrar` | RegistrarInformation | |
| `name_servers` | array | |
| `domain_status` | array | |
| `whois_raw_registery` | string | Raw registry WHOIS text (field name spelled as the API returns it) |
</details>
**Usage**
Python
```python
"""Live WHOIS Lookup: GET https://api.whoisfreaks.com/v2.0/whois/live
Run it with your API key in the environment:
WHOISFREAKS_API_KEY=your_api_key python WhoisLive.py
"""
import json
import os
import whoisfreaks
config = whoisfreaks.Configuration()
config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request
with whoisfreaks.ApiClient(config) as client:
api = whoisfreaks.WHOISApi(client)
# whois_live parameters:
# domain_name (str, required)
# format (str, optional, keyword): one of json, xml; default "json"
result = api.whois_live("whoisfreaks.com")
print(json.dumps(result.to_dict(), indent=2))
```
TypeScript
```typescript
// Live WHOIS Lookup: GET https://api.whoisfreaks.com/v2.0/whois/live
// Run: WHOISFREAKS_API_KEY=your_api_key npx tsx WhoisLive.ts
import { Configuration, WHOISApi, ResponseError } from "whoisfreaks";
// Set the API key once; the client adds it to every request.
const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY });
const api = new WHOISApi(config);
// whoisLive({ domainName, format? })
// domainName (string, required)
// format ("json" | "xml", optional): default "json"
async function main(): Promise {
const result = await api.whoisLive({ domainName: "whoisfreaks.com" });
console.log(JSON.stringify(result, null, 2));
}
main().catch(async (err: unknown) => {
// API errors carry the HTTP response
if (err instanceof ResponseError) {
console.error(`HTTP ${err.response.status}: ${await err.response.text()}`);
} else {
console.error(err);
}
process.exitCode = 1;
});
```
</details>
Go
```go
// Runnable example: Live WHOIS Lookup (GET /v2.0/whois/live)
// Run it from the Getting Started module: save it as main.go, then `go run .`
// Parameters for whoisLive (GET /v2.0/whois/live):
// - domainName (string, required)
// - format (string (one of: json, xml), optional)
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go"
)
func main() {
// Set the API key once on the context; every call made with ctx sends it.
ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys,
map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}})
client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration())
result, _, err := client.WHOISAPI.WhoisLive(ctx).DomainName("whoisfreaks.com").Execute()
if err != nil {
log.Fatal(err)
}
out, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(out))
}
```
---
## Bulk WHOIS Lookup
`POST https://api.whoisfreaks.com/v2.0/bulkwhois/live`
Up to 100 domains in one request. 1 credit per successful domain.
**Parameters**
| Parameter | In | Required | Type | Default | Description |
|-----------|----|----------|------|---------|-------------|
| `format` | query | no | string | `json` | (one of: json, xml) |
**Request body** (`application/json`, model `BulkWhoisRequest`)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domainNames` | array | yes | Up to 100 items. |
Example: `{"domainNames": ["whoisfreaks.com", "jfreaks.com"]}`
**Response** (`BulkWhoisResponse`)
| Field | Type | Description |
|-------|------|-------------|
| `bulk_whois_response` | array | |
BulkWhoisItem object
| Field | Type | Description |
|-------|------|-------------|
| `status` | boolean | |
| `domain_name` | string | |
| `error` | string | |
| `query_time` | string | |
| `whois_server` | string | |
| `domain_registered` | string | |
| `secure_dns` | boolean | |
| `domain_handle` | string | |
| `create_date` | string | |
| `update_date` | string | |
| `expiry_date` | string | |
| `domain_registrar` | RegistrarInformation | |
| `reseller_contact` | ResellerContact | |
| `registrant_contact` | PersonalInformation | |
| `administrative_contact` | PersonalInformation | |
| `technical_contact` | PersonalInformation | |
| `billing_contact` | PersonalInformation | |
| `eligibility_info` | EligibilityInfo | |
| `abuse_contact` | RegistrarInformation | |
| `name_servers` | array | |
| `domain_status` | array | |
| `whois_raw_domain` | string | |
| `registry_data` | RegistryData | |
</details>
**Usage**
Python
```python
"""Bulk WHOIS Lookup: POST https://api.whoisfreaks.com/v2.0/bulkwhois/live
Run it with your API key in the environment:
WHOISFREAKS_API_KEY=your_api_key python BulkWhois.py
"""
import json
import os
import whoisfreaks
config = whoisfreaks.Configuration()
config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request
with whoisfreaks.ApiClient(config) as client:
api = whoisfreaks.WHOISApi(client)
# bulk_whois parameters:
# bulk_whois_request (BulkWhoisRequest, required): request body
# format (str, optional, keyword): one of json, xml; default "json"
body = whoisfreaks.BulkWhoisRequest(domain_names=["whoisfreaks.com", "jfreaks.com"])
result = api.bulk_whois(body)
print(json.dumps(result.to_dict(), indent=2))
```
TypeScript
```typescript
// Bulk WHOIS Lookup: POST https://api.whoisfreaks.com/v2.0/bulkwhois/live
// Run: WHOISFREAKS_API_KEY=your_api_key npx tsx BulkWhois.ts
import { Configuration, WHOISApi, ResponseError, type BulkWhoisRequest } from "whoisfreaks";
// Set the API key once; the client adds it to every request.
const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY });
const api = new WHOISApi(config);
// bulkWhois({ bulkWhoisRequest, format? })
// bulkWhoisRequest (BulkWhoisRequest, required): request body
// format ("json" | "xml", optional): default "json"
async function main(): Promise {
const body: BulkWhoisRequest = { domainNames: ["whoisfreaks.com", "jfreaks.com"] };
const result = await api.bulkWhois({ bulkWhoisRequest: body });
console.log(JSON.stringify(result, null, 2));
}
main().catch(async (err: unknown) => {
// API errors carry the HTTP response
if (err instanceof ResponseError) {
console.error(`HTTP ${err.response.status}: ${await err.response.text()}`);
} else {
console.error(err);
}
process.exitCode = 1;
});
```
</details>
Go
```go
// Runnable example: Bulk WHOIS Lookup (POST /v2.0/bulkwhois/live)
// Run it from the Getting Started module: save it as main.go, then `go run .`
// Parameters for bulkWhois (POST /v2.0/bulkwhois/live):
// - format (string (one of: json, xml), optional)
// - body: BulkWhoisRequest (required): request body object
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go"
)
func main() {
// Set the API key once on the context; every call made with ctx sends it.
ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys,
map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}})
client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration())
body := whoisfreaks.NewBulkWhoisRequest([]string{"whoisfreaks.com", "jfreaks.com"})
result, _, err := client.WHOISAPI.BulkWhois(ctx).BulkWhoisRequest(*body).Execute()
if err != nil {
log.Fatal(err)
}
out, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(out))
}
```
---
## Historical WHOIS records for a domain
`GET https://api.whoisfreaks.com/v2.0/whois/history`
Every WHOIS record captured for the domain since 1986, in one response (no pagination). Cost 2 credits.
**Parameters**
| Parameter | In | Required | Type | Default | Description |
|-----------|----|----------|------|---------|-------------|
| `domainName` | query | yes | string | | Domain to fetch historical WHOIS records for |
| `format` | query | no | string | | (one of: json, xml) |
**Response** (`WhoisHistoricalResponse`)
| Field | Type | Description |
|-------|------|-------------|
| `status` | boolean | |
| `whois` | string | |
| `total_records` | string | |
| `whois_domains_historical` | array | |
WhoisHistoricalItem object
| Field | Type | Description |
|-------|------|-------------|
| `num` | integer | |
| `status` | boolean | |
| `domain_name` | string | |
| `query_time` | string | |
| `whois_server` | string | |
| `domain_registered` | string | |
| `secure_dns` | boolean | |
| `domain_handle` | string | |
| `create_date` | string | |
| `update_date` | string | |
| `expiry_date` | string | |
| `domain_registrar` | RegistrarInformation | |
| `reseller_contact` | ResellerContact | |
| `registrant_contact` | PersonalInformation | |
| `administrative_contact` | PersonalInformation | |
| `technical_contact` | PersonalInformation | |
| `billing_contact` | PersonalInformation | |
| `eligibility_info` | EligibilityInfo | |
| `abuse_contact` | RegistrarInformation | |
| `name_servers` | array | |
| `domain_status` | array | |
| `whois_raw_domain` | string | |
| `registry_data` | RegistryData | |
</details>
**Usage**
Python
```python
"""Historical WHOIS records for a domain: GET https://api.whoisfreaks.com/v2.0/whois/history
Run it with your API key in the environment:
WHOISFREAKS_API_KEY=your_api_key python WhoisHistory.py
"""
import json
import os
import whoisfreaks
config = whoisfreaks.Configuration()
config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request
with whoisfreaks.ApiClient(config) as client:
api = whoisfreaks.WHOISApi(client)
# whois_history parameters:
# domain_name (str, required): Domain to fetch historical WHOIS records for
# format (str, optional, keyword): one of json, xml
result = api.whois_history("whoisfreaks.com")
print(json.dumps(result.to_dict(), indent=2))
```
TypeScript
```typescript
// Historical WHOIS records for a domain: GET https://api.whoisfreaks.com/v2.0/whois/history
// Run: WHOISFREAKS_API_KEY=your_api_key npx tsx WhoisHistory.ts
import { Configuration, WHOISApi, ResponseError } from "whoisfreaks";
// Set the API key once; the client adds it to every request.
const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY });
const api = new WHOISApi(config);
// whoisHistory({ domainName, format? })
// domainName (string, required): Domain to fetch historical WHOIS records for
// format ("json" | "xml", optional)
async function main(): Promise {
const result = await api.whoisHistory({ domainName: "whoisfreaks.com" });
console.log(JSON.stringify(result, null, 2));
}
main().catch(async (err: unknown) => {
// API errors carry the HTTP response
if (err instanceof ResponseError) {
console.error(`HTTP ${err.response.status}: ${await err.response.text()}`);
} else {
console.error(err);
}
process.exitCode = 1;
});
```
</details>
Go
```go
// Runnable example: Historical WHOIS records for a domain (GET /v2.0/whois/history)
// Run it from the Getting Started module: save it as main.go, then `go run .`
// Parameters for whoisHistory (GET /v2.0/whois/history):
// - domainName (string, required): Domain to fetch historical WHOIS records for
// - format (string (one of: json, xml), optional)
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go"
)
func main() {
// Set the API key once on the context; every call made with ctx sends it.
ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys,
map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}})
client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration())
result, _, err := client.WHOISAPI.WhoisHistory(ctx).DomainName("whoisfreaks.com").Execute()
if err != nil {
log.Fatal(err)
}
out, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(out))
}
```
---
## Reverse WHOIS lookup by keyword
`GET https://api.whoisfreaks.com/v2.0/whois/reverse`
**Parameters**
| Parameter | In | Required | Type | Default | Description |
|-----------|----|----------|------|---------|-------------|
| `keyword` | query | yes | string | | Keyword to search across WHOIS records |
| `page` | query | no | integer | | Page number |
| `format` | query | no | string | | (one of: json, xml) |
**Response** (`ReverseWhoisResponse`)
| Field | Type | Description |
|-------|------|-------------|
| `total_Result` | integer | |
| `total_Pages` | integer | |
| `current_Page` | integer | |
| `whois_domains_historical` | array | |
WhoisHistoricalItem object
| Field | Type | Description |
|-------|------|-------------|
| `num` | integer | |
| `status` | boolean | |
| `domain_name` | string | |
| `query_time` | string | |
| `whois_server` | string | |
| `domain_registered` | string | |
| `secure_dns` | boolean | |
| `domain_handle` | string | |
| `create_date` | string | |
| `update_date` | string | |
| `expiry_date` | string | |
| `domain_registrar` | RegistrarInformation | |
| `reseller_contact` | ResellerContact | |
| `registrant_contact` | PersonalInformation | |
| `administrative_contact` | PersonalInformation | |
| `technical_contact` | PersonalInformation | |
| `billing_contact` | PersonalInformation | |
| `eligibility_info` | EligibilityInfo | |
| `abuse_contact` | RegistrarInformation | |
| `name_servers` | array | |
| `domain_status` | array | |
| `whois_raw_domain` | string | |
| `registry_data` | RegistryData | |
</details>
**Usage**
Python
```python
"""Reverse WHOIS lookup by keyword: GET https://api.whoisfreaks.com/v2.0/whois/reverse
Run it with your API key in the environment:
WHOISFREAKS_API_KEY=your_api_key python WhoisReverse.py
"""
import json
import os
import whoisfreaks
config = whoisfreaks.Configuration()
config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request
with whoisfreaks.ApiClient(config) as client:
api = whoisfreaks.WHOISApi(client)
# whois_reverse parameters:
# keyword (str, required): Keyword to search across WHOIS records
# page (int, optional, keyword): Page number
# format (str, optional, keyword): one of json, xml
result = api.whois_reverse("whoisfreaks", page=1)
print(json.dumps(result.to_dict(), indent=2))
```
TypeScript
```typescript
// Reverse WHOIS lookup by keyword: GET https://api.whoisfreaks.com/v2.0/whois/reverse
// Run: WHOISFREAKS_API_KEY=your_api_key npx tsx WhoisReverse.ts
import { Configuration, WHOISApi, ResponseError } from "whoisfreaks";
// Set the API key once; the client adds it to every request.
const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY });
const api = new WHOISApi(config);
// whoisReverse({ keyword, page?, format? })
// keyword (string, required): Keyword to search across WHOIS records
// page (number, optional): Page number
// format ("json" | "xml", optional)
async function main(): Promise {
const result = await api.whoisReverse({ keyword: "whoisfreaks", page: 1 });
console.log(JSON.stringify(result, null, 2));
}
main().catch(async (err: unknown) => {
// API errors carry the HTTP response
if (err instanceof ResponseError) {
console.error(`HTTP ${err.response.status}: ${await err.response.text()}`);
} else {
console.error(err);
}
process.exitCode = 1;
});
```
</details>
Go
```go
// Runnable example: Reverse WHOIS lookup by keyword (GET /v2.0/whois/reverse)
// Run it from the Getting Started module: save it as main.go, then `go run .`
// Parameters for whoisReverse (GET /v2.0/whois/reverse):
// - keyword (string, required): Keyword to search across WHOIS records
// - page (integer, optional): Page number
// - format (string (one of: json, xml), optional)
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go"
)
func main() {
// Set the API key once on the context; every call made with ctx sends it.
ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys,
map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}})
client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration())
result, _, err := client.WHOISAPI.WhoisReverse(ctx).Keyword("whoisfreaks").Page(1).Execute()
if err != nil {
log.Fatal(err)
}
out, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(out))
}
```
---