Geocoding Phone Numbers

The PhoneNumberOfflineGeocoder provides geographic location descriptions for phone numbers in multiple languages. This is useful for displaying where a phone number is from to your users.

This feature works offline using precompiled metadata. It provides city or region-level information, not precise GPS coordinates.

Getting Started

Get Geocoder Instance

use libphonenumber\geocoding\PhoneNumberOfflineGeocoder;

$geocoder = PhoneNumberOfflineGeocoder::getInstance();

Parse a Phone Number

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$number = $phoneUtil->parse('044 668 18 00', 'CH');

Get Location Description

// Get description in English
$location = $geocoder->getDescriptionForNumber($number, 'en_US');
echo $location; // "Zurich"

Localized Descriptions

One of the most powerful features is multi-language support:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

// Parse a Swiss number
$swissNumber = $phoneUtil->parse('044 668 18 00', 'CH');

// English
echo $geocoder->getDescriptionForNumber($swissNumber, 'en_US');
// Output: Zurich

// German
echo $geocoder->getDescriptionForNumber($swissNumber, 'de_DE');
// Output: Zürich

// Italian
echo $geocoder->getDescriptionForNumber($swissNumber, 'it_IT');
// Output: Zurigo

// French
echo $geocoder->getDescriptionForNumber($swissNumber, 'fr_FR');
// Output: Zurich

Use the user’s preferred locale to automatically show location names in their language.

Examples from Different Countries

United States
United Kingdom
Germany

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

$usNumber = $phoneUtil->parse('+1 650 253 0000', 'US');

// English
echo $geocoder->getDescriptionForNumber($usNumber, 'en_US');
// Output: Mountain View, CA

// German
echo $geocoder->getDescriptionForNumber($usNumber, 'de_DE');
// Output: Mountain View, CA

// Korean
echo $geocoder->getDescriptionForNumber($usNumber, 'ko_KR');
// Output: 미국 (United States)

For some locales, if specific city data isn’t available, it falls back to the country name.

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

$gbNumber = $phoneUtil->parse('0161 496 0000', 'GB');

// For UK users
echo $geocoder->getDescriptionForNumber($gbNumber, 'en_GB');
// Output: Manchester

// For US users
echo $geocoder->getDescriptionForNumber($gbNumber, 'en_US');
// Output: United Kingdom

// For Korean users
echo $geocoder->getDescriptionForNumber($gbNumber, 'ko_KR');
// Output: 영국 (United Kingdom)

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

$deNumber = $phoneUtil->parse('030 12345678', 'DE');

// English
echo $geocoder->getDescriptionForNumber($deNumber, 'en_US');
// Output: Berlin

// German
echo $geocoder->getDescriptionForNumber($deNumber, 'de_DE');
// Output: Berlin

Working with Valid Numbers Only

For performance and accuracy, use getDescriptionForValidNumber() when you’ve already validated the number:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

$number = $phoneUtil->parse('+41 44 668 18 00', null);

// Validate first
if ($phoneUtil->isValidNumber($number)) {
    // More efficient if already validated
    $location = $geocoder->getDescriptionForValidNumber($number, 'en_US');
    echo $location; // Zurich
}

If you’re processing large batches of numbers and have already validated them, use getDescriptionForValidNumber() for better performance.

Handling Numbers Without Geo Data

Not all numbers have geographic data available:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

// Mobile numbers may not have specific location data
$mobileNumber = $phoneUtil->parse('+44 7400 123456', 'GB');
$location = $geocoder->getDescriptionForNumber($mobileNumber, 'en_US');

if (empty($location)) {
    echo "No location data available";
} else {
    echo $location; // May show "United Kingdom" or be empty
}

// Toll-free numbers typically don't have location data
$tollFree = $phoneUtil->parse('1-800-FLOWERS', 'US');
$location = $geocoder->getDescriptionForNumber($tollFree, 'en_US');
// May return empty string or country name

Mobile, toll-free, and some other number types may not have detailed geographic information.

Practical Examples

Contact List Display
Call Log Enhancement
API Response

function formatContactWithLocation(
    string $name,
    string $phoneNumber,
    string $userLocale
): array {
    $phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
    $geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();
    
    try {
        $number = $phoneUtil->parse($phoneNumber, null);
        
        $formatted = $phoneUtil->format(
            $number,
            \libphonenumber\PhoneNumberFormat::INTERNATIONAL
        );
        
        $location = $geocoder->getDescriptionForNumber(
            $number,
            $userLocale
        );
        
        return [
            'name' => $name,
            'phone' => $formatted,
            'location' => $location ?: 'Unknown',
            'type' => $phoneUtil->getNumberType($number)
        ];
        
    } catch (\libphonenumber\NumberParseException $e) {
        return [
            'name' => $name,
            'phone' => $phoneNumber,
            'location' => 'Invalid',
            'error' => true
        ];
    }
}

// Usage
$contact = formatContactWithLocation(
    'John Smith',
    '+41 44 668 18 00',
    'en_US'
);

echo "{$contact['name']}: {$contact['phone']} ({$contact['location']})";
// Output: John Smith: +41 44 668 18 00 (Zurich)

class CallLogFormatter
{
    private PhoneNumberUtil $phoneUtil;
    private PhoneNumberOfflineGeocoder $geocoder;
    
    public function __construct()
    {
        $this->phoneUtil = PhoneNumberUtil::getInstance();
        $this->geocoder = PhoneNumberOfflineGeocoder::getInstance();
    }
    
    public function formatCallLog(
        array $callLog,
        string $userRegion,
        string $userLocale
    ): array {
        $formatted = [];
        
        foreach ($callLog as $call) {
            try {
                $number = $this->phoneUtil->parse(
                    $call['number'],
                    $userRegion
                );
                
                $formatted[] = [
                    'timestamp' => $call['timestamp'],
                    'number' => $this->phoneUtil->format(
                        $number,
                        \libphonenumber\PhoneNumberFormat::INTERNATIONAL
                    ),
                    'location' => $this->geocoder->getDescriptionForNumber(
                        $number,
                        $userLocale
                    ),
                    'type' => $this->getNumberTypeLabel(
                        $this->phoneUtil->getNumberType($number)
                    ),
                    'duration' => $call['duration']
                ];
                
            } catch (\libphonenumber\NumberParseException $e) {
                $formatted[] = [
                    'timestamp' => $call['timestamp'],
                    'number' => $call['number'],
                    'location' => 'Unknown',
                    'type' => 'Unknown',
                    'duration' => $call['duration']
                ];
            }
        }
        
        return $formatted;
    }
    
    private function getNumberTypeLabel(int $type): string
    {
        return match($type) {
            \libphonenumber\PhoneNumberType::MOBILE => 'Mobile',
            \libphonenumber\PhoneNumberType::FIXED_LINE => 'Landline',
            \libphonenumber\PhoneNumberType::TOLL_FREE => 'Toll-Free',
            default => 'Unknown'
        };
    }
}

function enrichPhoneNumberData(
    string $phoneNumber,
    ?string $region = null
): array {
    $phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
    $geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();
    
    try {
        $number = $phoneUtil->parse($phoneNumber, $region);
        
        if (!$phoneUtil->isValidNumber($number)) {
            return [
                'valid' => false,
                'error' => 'Invalid phone number'
            ];
        }
        
        $regionCode = $phoneUtil->getRegionCodeForNumber($number);
        
        return [
            'valid' => true,
            'e164' => $phoneUtil->format(
                $number,
                \libphonenumber\PhoneNumberFormat::E164
            ),
            'international' => $phoneUtil->format(
                $number,
                \libphonenumber\PhoneNumberFormat::INTERNATIONAL
            ),
            'region' => $regionCode,
            'type' => $phoneUtil->getNumberType($number),
            'location' => [
                'en' => $geocoder->getDescriptionForValidNumber(
                    $number,
                    'en_US'
                ),
                'local' => $geocoder->getDescriptionForValidNumber(
                    $number,
                    $regionCode === 'US' ? 'en_US' : $regionCode . '_' . $regionCode
                )
            ]
        ];
        
    } catch (\libphonenumber\NumberParseException $e) {
        return [
            'valid' => false,
            'error' => $e->getMessage()
        ];
    }
}

// Usage
$data = enrichPhoneNumberData('+41 44 668 18 00');
/*
Result:
[
    'valid' => true,
    'e164' => '+41446681800',
    'international' => '+41 44 668 18 00',
    'region' => 'CH',
    'type' => 0,
    'location' => [
        'en' => 'Zurich',
        'local' => 'Zürich'
    ]
]
*/

Supported Locales

The geocoder supports many locales. Common ones include:

English: en_US, en_GB
European: de_DE, fr_FR, it_IT, es_ES, pt_PT, nl_NL
Asian: ja_JP, ko_KR, zh_CN, zh_TW
Others: ar, ru_RU, pl_PL, tr_TR

If a specific locale isn’t available, the geocoder will fall back to a more general description or English.

Best Practices

Use User's Locale

Always pass the user’s locale to show location names in their language

Validate First

Validate numbers before geocoding for best results and performance

Handle Empty Results

Not all numbers have location data - always check for empty strings

Cache Results

Cache geocoding results for frequently accessed numbers to improve performance

Limitations

What geocoding cannot do:

Provide GPS coordinates or street addresses
Track the current location of a mobile phone
Work with invalid or unparseable numbers
Guarantee location data for all number types (mobile, toll-free, etc.)

Next Steps

Carrier Mapping

Identify mobile carriers for phone numbers

Timezone Mapping

Get timezone information from phone numbers

Geocoder API Reference

Complete API documentation for geocoding

Number Types

Understanding different phone number types

Get Started

Core Concepts

Guides

Advanced

Geocoding Phone Numbers

Geocoding Phone Numbers

Getting Started

Localized Descriptions

Examples from Different Countries

Working with Valid Numbers Only

Handling Numbers Without Geo Data

Practical Examples

Supported Locales

Best Practices

Use User's Locale

Validate First

Handle Empty Results

Cache Results

Limitations

Next Steps

Carrier Mapping

Timezone Mapping

Geocoder API Reference

Number Types

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Geocoding Phone Numbers

​Getting Started

​Localized Descriptions

​Examples from Different Countries

​Working with Valid Numbers Only

​Handling Numbers Without Geo Data

​Practical Examples

​Supported Locales

​Best Practices

Use User's Locale

Validate First

Handle Empty Results

Cache Results

​Limitations

​Next Steps

Carrier Mapping

Timezone Mapping

Geocoder API Reference

Number Types

Build docs developers (and LLMs) love

Geocoding Phone Numbers

Getting Started

Localized Descriptions

Examples from Different Countries

Working with Valid Numbers Only

Handling Numbers Without Geo Data

Practical Examples

Supported Locales

Best Practices

Limitations

Next Steps