Name: Phone Number Lookup API: Validate & Get Carrier, Type, Locat
Brand: viv-data
SKU: api-viv-data-phone-lookup
Availability: InStock
Author: API Market

gia ly bui

# Phone Number Lookup — Carrier, Location, Type

## Overview
The Phone Number Lookup API provides comprehensive details for phone numbers worldwide. It allows developers to validate phone numbers, identify their country, carrier, and line type (mobile, landline, or VoIP). Built on Google's highly accurate `libphonenumber` library, this API ensures reliable international number parsing and formatting into the E.164 standard. It's an essential tool for enhancing data quality, improving communication reliability, and preventing fraud.

## Features
*   **Global Phone Number Validation:** Accurately validates phone numbers from any country.
*   **Carrier Identification:** Returns the service provider for a given phone number.
*   **Location Lookup:** Provides general geographic location information (e.g., city/state) associated with the number.
*   **Line Type Detection:** Identifies if a number is a mobile, landline, or VoIP (Voice over IP) line.
*   **E.164 Formatting:** Formats numbers into the international E.164 standard for consistent use.
*   **Comprehensive Number Details:** Includes country code, international and national formats, and a `possible` flag for ambiguous numbers.
*   **Invalid Number Detection:** Identifies invalid numbers, short codes, and premium rate numbers.
*   **Country Hinting:** Supports optional `country_hint` for numbers without international prefixes.

## Use Cases
*   **E-commerce & Fraud Prevention:** Validate customer contact details during registration or checkout to reduce fraud, ensure accurate shipping, and improve communication. Detect suspicious numbers (e.g., VoIP lines from high-risk regions).
*   **Telemarketing & Sales Optimization:** Clean calling lists by identifying invalid numbers, filtering out premium rate lines, and segmenting prospects by country, carrier, or mobile/landline status for targeted campaigns.
*   **Customer Service & Support:** Automatically enrich incoming call data with country, carrier, and location information to route inquiries efficiently and provide localized support.
*   **International Messaging & Communication Platforms:** Ensure message deliverability for SMS, WhatsApp, or other platforms by validating and formatting international numbers to prevent delivery failures.
*   **Application Development:** Integrate robust phone number validation and formatting capabilities into web and mobile applications to improve user data quality and enhance user experience.

## Pricing
The Phone Number Lookup API offers flexible pricing tiers based on your usage volume:
*   **Free Tier:** 1,000 requests per month
*   **Pro Tier:** $19.99 for 10,000 requests per month
    
1 API unit equals 1 phone number lookup processed. Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL
All API requests should be made to the following base URL:
`https://prod.api.market/api/v1/viv-data/phone-lookup`

### Authentication
Authentication is handled via an API key. Include your API key in the `x-api-market-key` header for every request:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Processing Mode
This API operates in **Synchronous Processing** mode. This means that a single API request directly returns the final result in its response. There are no job IDs, no polling endpoints, and no status checks required. For longer-running requests, it's recommended to implement a client-side request timeout of 30-60 seconds to accommodate network latency or processing variations.

### Endpoints

#### Quick Start Example
To quickly get started with a phone number lookup:

```bash
curl -H "x-api-market-key: YOUR_API_MARKET_KEY" "https://prod.api.market/api/v1/viv-data/phone-lookup/lookup?phone=+14155552671"
```

#### 1. Look up Phone Number Details
**GET `/lookup`**

This endpoint allows you to look up comprehensive details for a given phone number.

**Summary:** Look up phone number details including carrier, line type, and location.

**Parameters:**
*   `phone` (query, **required**, string): The phone number to look up, in international format (e.g., `+14155552671` or `+8613800138000`).
*   `country_hint` (query, *optional*, string): A two-letter ISO 3166-1 alpha-2 country code (e.g., `US`, `CN`). Used as a default country code if the provided phone number has no international prefix. Default is `CN`.

**Example Request:**
```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/lookup?phone=+14155552671" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Request with `country_hint`:**
```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/lookup?phone=13800138000&country_hint=CN" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Successful Response (200 OK):**
```json
{
  "phone": "+14155552671",
  "valid": true,
  "country": "US",
  "country_code": 1,
  "location": "San Francisco, CA",
  "carrier": "AT&T Mobility",
  "number_type": "MOBILE",
  "e164": "+14155552671",
  "international": "+1 415-555-2671",
  "national": "(415) 555-2671",
  "possible": true
}
```

#### 2. Health Check
**GET `/health`**

This endpoint can be used to check the operational status of the API.

**Summary:** Health check endpoint.

**Example Request:**
```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Successful Response (200 OK):**
```json
{}
```

#### 3. Root Endpoint
**GET `/`**

The root endpoint provides a basic confirmation that the API is reachable.

**Summary:** Root endpoint.

**Example Request:**
```bash
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Successful Response (200 OK):**
```json
{}
```

## Status Codes
*   **200 OK**: The request was successful, and the API returned the expected data.
*   **201 Created**: (Not typically used for this API, but a standard HTTP success code for resource creation).
*   **400 Bad Request**: The request was malformed or contained invalid input parameters. Check your request body and query parameters against the documentation.
*   **401 Unauthorized**: Your request is missing or contains an invalid API key. Ensure `x-api-market-key` header is present and correct.
*   **403 Forbidden**: Your API key is valid, but you do not have sufficient permissions to access the requested resource or perform the action.
*   **404 Not Found**: The requested API endpoint or resource does not exist. Verify the URL path.
*   **422 Unprocessable Entity**: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions (e.g., validation error for input).
*   **429 Too Many Requests**: You have exceeded the rate limit for your API key. See the Rate Limits section for more information.
*   **500 Internal Server Error**: An unexpected error occurred on the API server. If this error persists, please contact support.
*   **503 Service Unavailable**: The API service is temporarily unavailable, often due to maintenance or high load. Please try again after some time.

## Implementation Guide

### Example Code
Below are example code snippets in various languages demonstrating how to use the Phone Number Lookup API. These examples showcase synchronous requests, where the API call directly returns the final result.

#### JavaScript
This JavaScript example uses the `fetch` API to make a synchronous GET request to the `/lookup` endpoint.

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/phone-lookup";

async function lookupPhoneNumber(phoneNumber, countryHint = null) {
  let url = `${baseUrl}/lookup?phone=${encodeURIComponent(phoneNumber)}`;
  if (countryHint) {
    url += `&country_hint=${encodeURIComponent(countryHint)}`;
  }

  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey,
        "Accept": "application/json"
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const result = await response.json();
    return result;
  } catch (error) {
    console.error("Error looking up phone number:", error);
    throw error;
  }
}

// Example Usage:
(async () => {
  try {
    console.log("Looking up +14155552671...");
    const data1 = await lookupPhoneNumber("+14155552671");
    console.log("Lookup Result (+14155552671):", data1);

    console.log("\nLooking up 13800138000 with country hint CN...");
    const data2 = await lookupPhoneNumber("13800138000", "CN");
    console.log("Lookup Result (13800138000, CN):", data2);
  } catch (error) {
    console.error("Failed during example usage:", error);
  }
})();
```

#### Python
This Python example uses the `requests` library to perform a synchronous GET request for phone number lookup.

```python
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/phone-lookup"

def lookup_phone_number(phone_number, country_hint=None):
    headers = {
        "x-api-market-key": API_KEY,
        "Accept": "application/json"
    }
    params = {
        "phone": phone_number
    }
    if country_hint:
        params["country_hint"] = country_hint

    try:
        response = requests.get(f"{BASE_URL}/lookup", headers=headers, params=params)
        response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)
        return response.json()
    except requests.exceptions.HTTPError as e:
        print(f"HTTP error occurred: {e}")
        if e.response is not None:
            print(f"Response content: {e.response.text}")
        raise
    except requests.exceptions.ConnectionError as e:
        print(f"Connection error occurred: {e}")
        raise
    except requests.exceptions.Timeout as e:
        print(f"Timeout error occurred: {e}")
        raise
    except requests.exceptions.RequestException as e:
        print(f"An unexpected error occurred: {e}")
        raise

# Example Usage:
if __name__ == "__main__":
    try:
        print("Looking up +14155552671...")
        result1 = lookup_phone_number("+14155552671")
        print("Lookup Result (+14155552671):", json.dumps(result1, indent=2))
    except Exception as e:
        print("Failed to lookup +14155552671:", e)

    print("\n")

    try:
        print("Looking up 13800138000 with country hint CN...")
        result2 = lookup_phone_number("13800138000", "CN") # with country hint
        print("Lookup Result (13800138000, CN):", json.dumps(result2, indent=2))
    except Exception as e:
        print("Failed to lookup 13800138000 (CN):", e)
```

#### cURL
These cURL examples demonstrate how to make direct GET requests to the API for phone number lookups.

```bash
# Example: Look up phone number +14155552671
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/lookup?phone=+14155552671" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"

# Example: Look up phone number 13800138000 with a country hint for China
curl -X GET \
  "https://prod.api.market/api/v1/viv-data/phone-lookup/lookup?phone=13800138000&country_hint=CN" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -H "Accept: application/json"
```


## FAQ
**Q: What is the E.164 format?**

A: E.164 is an international numbering plan for public telephone networks. It specifies that a phone number should include a country code and a subscriber number, with a maximum of 15 digits, and typically starts with a `+` sign (e.g., `+14155552671`). This format ensures global uniqueness and compatibility.

**Q: What does `country_hint` do?**

A: The `country_hint` parameter provides a default country for numbers that do not include an international dialing code. For example, if you pass `phone=13800138000` and `country_hint=CN`, the API will assume the number is from China and attempt to parse it accordingly. If an international prefix is present in the `phone` number (e.g., `+8613800138000`), the `country_hint` is ignored.

**Q: How accurate is the data provided by the API?**

A: The API is based on Google's highly acclaimed `libphonenumber` library, which is also used by Android and Google apps. It offers excellent accuracy for parsing, validating, and extracting information from international phone numbers. However, real-time carrier or location data can occasionally vary due to network changes or number portability.

**Q: Can I look up multiple phone numbers in a single request?**

A: No, the API is designed for single phone number lookups per request. If you need to process multiple numbers, you will need to make individual requests for each number.

**Q: What is the difference between `phone`, `e164`, `international`, and `national` formats in the response?**

A:
*   `phone`: The input phone number, potentially normalized.
*   `e164`: The phone number formatted according to the E.164 standard (e.g., `+14155552671`).
*   `international`: The phone number formatted for international dialing (e.g., `+1 415-555-2671`).
*   `national`: The phone number formatted for national dialing within its country (e.g., `(415) 555-2671`).

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Validate and look up phone numbers worldwide. Get carrier, location, and type (mobile/landline/VoIP) with high accuracy, leveraging Google's libphonenumber.

Phone Number Lookup API: Validate & Get Carrier, Type, Locat

Free

Viv Data

Accurately validate and look up global phone number details, including carrier, line type, and location, leveraging Google's libphonenumber for superior interna