IP2WHOIS Information Lookup Getting Started: Quickstart Guide

Getting started overview

Integrating with the IP2WHOIS Information Lookup API involves a sequence of steps designed to ensure secure and efficient access to WHOIS data. This guide provides a rapid onboarding path, detailing the necessary actions from initial account setup to executing a functional API request. The process begins with creating an account on the IP2WHOIS platform, which grants access to a personalized dashboard. From this dashboard, users can generate and manage their unique API keys, which are essential for authenticating all subsequent API calls. Once an API key is obtained, the next step involves constructing and sending a request to the IP2WHOIS API endpoint, typically using a common HTTP client or one of the provided IP2WHOIS SDKs. This request will specify the domain or IP address for which WHOIS information is sought. The API will then return a structured JSON response containing details such as registrant information, administrative and technical contacts, registration and expiration dates, and associated name servers. Understanding the structure of this response is key to effectively parsing and utilizing the retrieved data within your applications.

The IP2WHOIS API supports various programming languages through its official SDKs, streamlining integration. Developers can choose from PHP, Python, Ruby, Java, Node.js, .NET, and Go. These SDKs handle much of the underlying HTTP request logic and response parsing, allowing developers to focus on application-specific functionality. For those preferring direct HTTP requests, the API follows RESTful principles, accepting standard GET requests with parameters for the target domain or IP and the API key. The structured JSON output is consistent and well-documented in the IP2WHOIS developer documentation, facilitating predictable data extraction.

Create an account and get keys

Before making any API requests, you must register for an IP2WHOIS account and generate an API key. This key authenticates your requests and associates them with your account's query allowance.

Account Creation Steps:

1. Navigate to the Signup Page: Go to the official IP2WHOIS pricing page.
2. Choose a Plan: Select either the "Free Plan" for up to 1,000 queries per month or a paid subscription plan, such as the "Pro 10k" starting at $29.90/month for 10,000 queries. All plans require account registration.
3. Complete Registration: Provide the required information, including your email address and a password.
4. Verify Email: Check your email inbox for a verification link from IP2WHOIS. Click this link to activate your account.

Obtaining Your API Key:

1. Log In: After successful registration and email verification, log in to your IP2WHOIS account.
2. Access Dashboard: You will be redirected to your user dashboard. Your unique API key will typically be displayed prominently on this page.
3. Copy API Key: Copy your API key. This key is a sensitive credential and should be kept secure. It will be required for every API request you make.

The API key is a crucial component for secure API communication, functioning similarly to an OAuth 2.0 access token in other services for authentication, as described in general OAuth 2.0 specification documents detailing client credential flows. Keep your API key confidential to prevent unauthorized usage and potential depletion of your query limits.

Your first request

Once you have your API key, you can make your first request. This example uses a simple HTTP GET request, but you can also use one of the IP2WHOIS SDKs for a more integrated approach.

API Endpoint and Parameters:

The base endpoint for WHOIS lookups is:

https://api.ip2whois.com/v2

Required parameters:

• key: Your API key.
• domain: The domain name you wish to look up (e.g., example.com).

Example Request (cURL):

Replace YOUR_API_KEY with your actual API key and google.com with the domain you want to query.

curl "https://api.ip2whois.com/v2?key=YOUR_API_KEY&domain=google.com"

Example Response (JSON):

{
  "domain": "google.com",
  "domain_id": "2138971_DOMAIN_COM-VRSN",
  "status": "clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited",
  "create_date": "1997-09-15T04:00:00-07:00",
  "update_date": "2019-09-09T18:39:04-07:00",
  "expire_date": "2028-09-14T21:00:00-07:00",
  "domain_age": "9792 days",
  "whois_server": "whois.markmonitor.com",
  "registrar": {
    "iana_id": "292",
    "name": "MarkMonitor Inc.",
    "url": "http://www.markmonitor.com"
  },
  "registrant": {
    "organization": "Google LLC",
    "street_address": "1600 Amphitheatre Parkway",
    "city": "Mountain View",
    "region": "CA",
    "zip_code": "94043",
    "country": "US",
    "email": "Select Request Entity in RDDS whois database",
    "phone": "+1.6502530000",
    "fax": "+1.6506440300"
  },
  "admin": {
    "organization": "Google LLC",
    "street_address": "1600 Amphitheatre Parkway",
    "city": "Mountain View",
    "region": "CA",
    "zip_code": "94043",
    "country": "US",
    "email": "Select Request Entity in RDDS whois database",
    "phone": "+1.6502530000",
    "fax": "+1.6506440300"
  },
  "tech": {
    "organization": "Google LLC",
    "street_address": "1600 Amphitheatre Parkway",
    "city": "Mountain View",
    "region": "CA",
    "zip_code": "94043",
    "country": "US",
    "email": "Select Request Entity in RDDS whois database",
    "phone": "+1.6502530000",
    "fax": "+1.6506440300"
  },
  "nameservers": [
    "ns1.google.com",
    "ns2.google.com",
    "ns3.google.com",
    "ns4.google.com"
  ]
}

This JSON output provides detailed WHOIS information, including registration dates, registrar details, and contact information for the registrant, administrative, and technical contacts. Depending on the domain and its privacy settings, some contact details might be redacted due to regulations like GDPR data protection rules.

Common next steps

After successfully making your first IP2WHOIS API call, consider these next steps to further integrate and optimize your usage:

1. Explore SDKs: If you are working in a supported language (PHP, Python, Ruby, Java, Node.js, .NET, Go), consider using the official IP2WHOIS SDKs. They abstract away HTTP request complexities and provide language-native objects for easier data handling.
2. Error Handling: Implement robust error handling in your application. The API returns meaningful HTTP status codes and JSON error messages for issues like invalid API keys, rate limits, or invalid domain queries. Refer to the developer documentation for a complete list of error codes and their meanings.
3. Rate Limiting: Be aware of your plan's query limits (e.g., 1,000 queries/month for the free tier). Implement a caching strategy for frequently queried domains or use exponential backoff for retries to avoid exceeding limits, as recommended for general API best practices.
4. Advanced Queries: The IP2WHOIS API supports additional features beyond basic domain lookups. Explore options for IP address WHOIS lookups or querying specific WHOIS fields if your needs extend beyond the basic domain information.
5. Data Parsing and Storage: Develop logic to parse the JSON response and extract the specific data points relevant to your application. Consider how you will store this data if persistent access is required, adhering to data retention policies and privacy regulations.
6. Monitor Usage: Regularly check your IP2WHOIS dashboard to monitor your API key usage and ensure you remain within your plan's limits.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a quick reference table and common troubleshooting steps:

Quick Reference Troubleshooting Table:

Common Issues and Solutions:

• 401 Unauthorized: Invalid API Key:
  • Solution: Double-check your API key for typos. Ensure you're using the key from your IP2WHOIS dashboard. Regenerate the key if necessary.
• 400 Bad Request: Missing or Invalid Parameter:
  • Solution: Verify that both key and domain parameters are present in your request URL. Ensure the domain name is correctly formatted (e.g., example.com, not http://example.com).
• 402 Payment Required: Query Limit Exceeded:
  • Solution: You have likely used all queries available in your current plan. Check your usage on the IP2WHOIS dashboard. Upgrade your plan or wait for the next billing cycle.
• 500 Internal Server Error:
  • Solution: This indicates an issue on the IP2WHOIS server side. While rare, it's best to wait a few minutes and retry the request. If the issue persists, contact IP2WHOIS support with your query details.
• Network Connection Issues:
  • Solution: Ensure your internet connection is stable. If making requests from an internal network, check firewall rules that might be blocking outbound API calls.