🌟 RealCarrier Beta v1.1.0 🌟

English Version | 中文版

Lightweight and efficient US phone number carrier lookup tool with bilingual interface and fast batch query support

---

📝 Update Log

Beta v1.1.0 (2025-04-10)

• Added geographic location information (city, state) display in query results
• Added port status and porting date information display
• Optimized carrier name display using more accurate spid_carrier_name
• Enhanced batch query results display for consistency with single number query

Beta v1.0.1 (2025-04-09)

• Enhanced Virtual Number Identification: Added intelligent identification for 38 common virtual number providers
• Improved UI Display: Added specific labeling for virtual number providers in query results
• Enhanced CSV Export: Added "is_virtual" column to batch query results
• Fixed Carrier Type Detection: Corrected the issue where number types weren't properly identified

Beta v1.0.0 (2025-03-06)

• Program completely restructured, now supports dual API providers: Telnyx and Twilio
• Users can choose to use one or both providers as needed
• Added provider switching functionality, easily switch in the main menu
• Optimized system information display, more accurately showing OS and processor information
• Improved error handling and internationalization support

📱 Project Overview

RealCarrier is a professional US phone number status query system that provides essential support for communication service providers, anti-fraud systems, and marketing compliance. Through a clean interface and powerful features, it helps users quickly obtain carrier information, number type, and local number portability status.

🔍 Core Principles

Local Number Portability (LNP)

Local Number Portability is a service mandated by US telecommunications regulations that allows users to retain their original phone numbers when changing carriers. Since the Telecommunications Act of 1996, this service has become the foundation of the US telecommunications market competition, with the NPAC database recording over 600 million number transfers.

When a number is transferred, its routing information is updated while the original allocation information remains unchanged, creating challenges in identifying the real carrier. For example, a number originally assigned to AT&T may now be serviced by T-Mobile.

Number Types

Type	Description
Physical Numbers	Traditional phone numbers associated with actual SIM cards and physical devices, provided by traditional carriers (AT&T, Verizon, T-Mobile, etc.)
Virtual Numbers	Numbers provided through VoIP services, not dependent on specific physical locations or devices, offered by virtual operators (Twilio, Bandwidth, Telnyx, etc.)

Distinguishing between these two types is essential for identifying potential fraudulent activities, verifying user identities, and ensuring communication compliance.

🌐 API Providers

RealCarrier supports two leading telecommunications API providers:

• Telnyx: A global communications platform that provides direct access to the NPAC database, offering the most accurate number portability information
• Twilio: A world-leading communications API provider whose Lookup API offers phone number verification and carrier information query services

Special Notice: the IP address used during Telnyx registration and the payment method (credit card/PayPal) must originate from the same country. For example, if you register with a Singapore IP and pay with a US PayPal account, your registration will be rejected. However, if you register with a US IP and use a US PayPal account, it will not be rejected.

{
  "country_code": "US",
  "national_format": "(406) XXX-XXX",
  "phone_number": "+1406XXXXXXX",
  "fraud": null,
  "carrier": {
    "mobile_country_code": "",
    "mobile_network_code": "",
    "name": "T-MOBILE USA, INC.",
    "type": "mobile",
    "error_code": null,
    "normalized_carrier": "T-Mobile USA"
  },
  "caller_name": {
    "caller_name": "WIRELESS CALLER",
    "error_code": null
  },
  "nnid_override": null,
  "portability": {
    "lrn": null,
    "ported_status": "",
    "ported_date": "",
    "ocn": "6034",
    "line_type": "mobile",
    "spid": "",
    "spid_carrier_name": "SPRINT SPECTRUM L.P.- MT",
    "spid_carrier_type": "",
    "altspid": "",
    "altspid_carrier_name": "",
    "altspid_carrier_type": "",
    "city": "MISSOULA",
    "state": "Montana"
  },
  "valid_number": true,
  "record_type": "number_lookup"
}

📖 Telnyx Number Lookup API Guide

📱 Telnyx Number Lookup API Developer Guide

This guide provides essential information for developers looking to integrate the Telnyx Number Lookup API into the RealCarrier project.

🔑 Prerequisites & Account Setup

1. Create a Telnyx Account

   • Sign up at Telnyx.com
   • Complete the Know Your Customer (KYC) verification process
   • Fund your account with the minimum required deposit

2. API Key Access

   • Navigate to the API Keys section in your Telnyx Portal
   • Generate a new API key for your application
   • Store this key securely as it will be needed for all API requests

3. IP Compatibility Note

   • Ensure that the IP address used during registration matches the country of your payment method

📋 Understanding the Number Lookup API

The Number Lookup API provides detailed information about phone numbers in the United States, with particular emphasis on:

1. Carrier Information

   • Current carrier details
   • Line type (mobile, landline, VoIP)
   • Mobile country and network codes (when applicable)

2. Portability Data

   • Local Number Portability (LNP) status
   • Original carrier information via SPID
   • Port date (when a number has been transferred)
   • OCN (Operating Company Number)

3. Geographic Details

   • City and state information
   • Rate center data

4. Optional Features

   • Caller name information
   • Fraud risk assessment
   • Additional carrier details

📊 API Response Structure

The API returns a JSON response with the following key sections:

1. Basic Number Information

   • country_code: The country code (e.g., "US")
   • national_format: Formatted display of the number
   • phone_number: The full E.164 format number
   • valid_number: Boolean indicating number validity

2. Carrier Section

   • name: The carrier's official name
   • normalized_carrier: A standardized version of the carrier name
   • type: The line type (mobile, landline, voip)

3. Portability Section

   • ported_status: Indicates if the number has been ported
   • ported_date: Date of the most recent port
   • spid_carrier_name: The original carrier name (most accurate)
   • city and state: Geographic location

💡 Integration Best Practices

1. Error Handling

   • Implement robust error handling for API rate limits
   • Account for potential network connectivity issues
   • Handle invalid phone number formats gracefully

2. Caching Strategy

   • Implement a local cache to store lookup results
   • Set appropriate expiration times for cached data
   • Consider database storage for frequently queried numbers

3. Virtual Number Detection

   • Look for carrier.type value of "voip"
   • Check carrier names against the virtual provider database

🚀 Key Features

Feature	Description
🔑 API Key Management	Securely store and manage your Telnyx and Twilio API keys
🔄 Dual API Providers	Support for both Telnyx and Twilio, with flexible selection based on user needs
🔍 Single Number Query	Quickly query carrier information for a single phone number
📊 Batch Query	Efficiently query multiple numbers from a CSV file
💾 Smart Caching	Multi-level caching strategy to reduce API calls and lower costs
🌐 Bilingual Interface	Seamless switching between Chinese and English to meet different user needs
💻 Convenient CLI	User-friendly CLI interface and advanced command-line tools

📥 Installation Guide

MacOS

# Clone repository
git clone https://github.com/yagami1997/realcarrier.git
cd realcarrier

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Windows 11

# Clone repository
git clone https://github.com/yagami1997/realcarrier.git
cd realcarrier

# Create virtual environment
python -m venv venv

# Activate virtual environment (CMD)
venv\Scripts\activate.bat
# Or (PowerShell)
.\venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

Ubuntu

# Clone repository
git clone https://github.com/yagami1997/realcarrier.git
cd realcarrier

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

💡 Usage Guide

Launch Program

After activating the virtual environment, run the main program:

python main.py

API Key Configuration

1. Select "1. 🔑 API Key Management" from the main menu
2. Choose the API provider you want to configure (Telnyx or Twilio)
3. Enter the corresponding API key as prompted
4. The key will be securely stored in the local configuration file

Single Number Query

1. Select "2. 🔍 Query Single Phone" from the main menu
2. Enter a 10-digit US phone number (e.g., 8772427372)
3. The system will display detailed information about the number

Batch Query

1. Select "3. 📊 Batch Query CSV File" from the main menu
2. Enter the path to the CSV file containing phone numbers
3. Specify the path for the output results file
4. The system will process all numbers in batch and generate a results file

Cache Management

1. Select "4. 💾 Cache Management" from the main menu
2. Choose a cache operation:
   • Display cache statistics
   • Clear all cache
   • Set cache expiration time

Language Settings

The program supports both Chinese and English interfaces. You can select "6. 🌐 Language Settings" in the main menu to switch:

• Select 1 to switch to Chinese
• Select 2 to switch to English

📋 Advanced CLI Usage

In addition to the interactive interface, this project also provides a command-line tool (lnp) for advanced users:

# Configure API key
lnp config set-key

# Query a single number
lnp lookup +14155552671

# Batch query
lnp batch numbers.csv -o results.csv

# Manage cache
lnp cache clear
lnp cache info

Output Examples

Command Line Output

┌────────────────────────────────┐
│ Phone Number: +14155552671     │
├────────────────────────────────┤
│ Carrier: T-Mobile USA, Inc.    │
│ Number Type: mobile            │
│ Ported: Yes                    │
│ Original Carrier: AT&T Mobility│
└────────────────────────────────┘

CSV Output Example

Phone Number	Carrier	Number Type	Ported	Original Carrier
+14155552671	T-Mobile USA, Inc.	mobile	Yes	AT&T Mobility
+14155552672	Verizon Wireless	mobile	No	-

👨‍💻 Developer Resources

Setting Up Development Environment

# Create virtual environment
python -m venv venv

# Activate environment
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

Running Tests

pytest

⚠️ Important Notes

• This tool uses the Telnyx and Twilio APIs, which may incur API call fees
• Critical Requirements:
  • Telnyx: Requires completed KYC and deposit
  • Twilio: Requires identity verification and account funding
• Ensure your API account status is normal before use to avoid query failures

⚖️ License

This project is released under the GNU General Public License v3.0 (GPL 3.0).

---

Last Updated: 2025-04-09 15:30:42 (Pacific Time)