0
# Geographic Services
1

2
Location-based services that provide geographic context for phone numbers, including geocoding to determine physical locations, carrier identification for mobile network operators, and timezone detection for scheduling and localization purposes.
3

4
## Capabilities
5

6
### Region and Country Code Services
7

8
Functions for mapping between phone numbers, country codes, and region identifiers.
9

10
```python { .api }
11
def region_code_for_number(numobj: PhoneNumber) -> str | None:
12
    """
13
    Get region code for a phone number.
14
    
15
    Parameters:
16
    - numobj: PhoneNumber to get region for
17
    
18
    Returns:
19
    Region code (e.g., "US", "GB") or None if not determinable
20
    """
21

22
def region_code_for_country_code(country_code: int) -> str:
23
    """
24
    Get main region code for a country calling code.
25
    
26
    Parameters:
27
    - country_code: Country calling code (e.g., 1, 44, 33)
28
    
29
    Returns:
30
    Primary region code for the country code
31
    """
32

33
def region_codes_for_country_code(country_code: int) -> tuple[str, ...]:
34
    """
35
    Get all region codes that use the specified country code.
36
    
37
    Parameters:
38
    - country_code: Country calling code
39
    
40
    Returns:
41
    Tuple of all region codes using this country code
42
    """
43

44
def country_code_for_region(region_code: str) -> int:
45
    """
46
    Get country calling code for a region.
47
    
48
    Parameters:
49
    - region_code: Region identifier (e.g., "US", "GB")
50
    
51
    Returns:
52
    Country calling code for the region, 0 if invalid region
53
    """
54

55
def country_code_for_valid_region(region_code: str) -> int:
56
    """
57
    Get country code for region, assuming region is valid.
58
    
59
    Parameters:
60
    - region_code: Valid region identifier
61
    
62
    Returns:
63
    Country calling code for the region
64
    """
65
```
66

67
**Usage Examples:**
68

69
```python
70
phone = phonenumbers.parse("+442083661177")
71

72
# Get region for a number
73
region = phonenumbers.region_code_for_number(phone)  # "GB"
74

75
# Map country codes to regions
76
main_region = phonenumbers.region_code_for_country_code(44)  # "GB"
77
all_regions = phonenumbers.region_codes_for_country_code(1)  # ("US", "CA", "PR", ...)
78

79
# Map regions to country codes
80
country_code = phonenumbers.country_code_for_region("GB")  # 44
81
us_code = phonenumbers.country_code_for_region("US")  # 1
82

83
# Handle multiple regions with same country code
84
phone_us = phonenumbers.parse("+12125551234")  # New York number
85
region_us = phonenumbers.region_code_for_number(phone_us)  # "US"
86

87
phone_ca = phonenumbers.parse("+14161234567")  # Toronto number  
88
region_ca = phonenumbers.region_code_for_number(phone_ca)  # "CA"
89
```
90

91
### Geographic Classification
92

93
Functions to determine if phone numbers are tied to specific geographic locations.
94

95
```python { .api }
96
def is_number_geographical(numobj: PhoneNumber) -> bool:
97
    """
98
    Check if number represents a geographical location.
99
    
100
    Parameters:
101
    - numobj: PhoneNumber to check
102
    
103
    Returns:
104
    True if the number is tied to a specific geographic area
105
    """
106

107
def is_number_type_geographical(num_type: int, country_code: int) -> bool:
108
    """
109
    Check if number type represents geographical numbers in given country.
110
    
111
    Parameters:
112
    - num_type: PhoneNumberType value
113
    - country_code: Country calling code
114
    
115
    Returns:
116
    True if the number type is geographical in the specified country
117
    """
118
```
119

120
**Usage Examples:**
121

122
```python
123
landline = phonenumbers.parse("+442083661177")  # UK landline
124
mobile = phonenumbers.parse("+447700123456")    # UK mobile
125
toll_free = phonenumbers.parse("+18001234567")  # US toll-free
126

127
# Check if numbers are geographical
128
is_geo_landline = phonenumbers.is_number_geographical(landline)  # True
129
is_geo_mobile = phonenumbers.is_number_geographical(mobile)      # False (in UK)
130
is_geo_toll_free = phonenumbers.is_number_geographical(toll_free) # False
131

132
# Check if number types are geographical in specific countries
133
is_fixed_geo_uk = phonenumbers.is_number_type_geographical(
134
    phonenumbers.PhoneNumberType.FIXED_LINE, 44
135
)  # True
136

137
is_mobile_geo_uk = phonenumbers.is_number_type_geographical(
138
    phonenumbers.PhoneNumberType.MOBILE, 44
139
)  # False
140
```
141

142
### Geocoding Services
143

144
Functions to get human-readable geographic descriptions for phone numbers.
145

146
```python { .api }
147
def description_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
148
    """
149
    Get geographic description (city/region) for phone number.
150
    
151
    Parameters:
152
    - numobj: PhoneNumber to get description for
153
    - lang: Language code for description (e.g., "en", "fr", "de")
154
    - script: Script code for language variants (optional)
155
    - region: Region code for localization (optional)
156
    
157
    Returns:
158
    Geographic description string, empty if unavailable
159
    """
160

161
def description_for_valid_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
162
    """
163
    Get description for number, assuming it's already validated.
164
    
165
    Parameters:
166
    - numobj: Valid PhoneNumber to get description for
167
    - lang: Language code for description
168
    - script: Script code for language variants (optional)
169
    - region: Region code for localization (optional)
170
    
171
    Returns:
172
    Geographic description string
173
    """
174

175
def country_name_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
176
    """
177
    Get country name for phone number in specified language.
178
    
179
    Parameters:
180
    - numobj: PhoneNumber to get country for
181
    - lang: Language code for country name
182
    - script: Script code for language variants (optional)
183
    - region: Region code for localization (optional)
184
    
185
    Returns:
186
    Country name string in requested language
187
    """
188
```
189

190
**Usage Examples:**
191

192
```python
193
# Import geocoder functions
194
from phonenumbers import geocoder
195

196
# Get geographic descriptions
197
uk_phone = phonenumbers.parse("+442083661177")
198
description_en = geocoder.description_for_number(uk_phone, "en")  # "London"
199
description_fr = geocoder.description_for_number(uk_phone, "fr")  # "Londres"
200

201
# Get country names
202
country_en = geocoder.country_name_for_number(uk_phone, "en")  # "United Kingdom"
203
country_de = geocoder.country_name_for_number(uk_phone, "de")  # "Vereinigtes Königreich"
204

205
# US number with area code
206
us_phone = phonenumbers.parse("+12125551234")  # New York area code
207
ny_description = geocoder.description_for_number(us_phone, "en")  # "New York, NY"
208

209
# For performance with pre-validated numbers
210
description = geocoder.description_for_valid_number(uk_phone, "en")
211
```
212

213
### Carrier Information Services
214

215
Functions to identify mobile network operators and carrier information.
216

217
```python { .api }
218
def name_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
219
    """
220
    Get carrier name for phone number in specified language.
221
    
222
    Parameters:
223
    - numobj: PhoneNumber to get carrier for
224
    - lang: Language code for carrier name
225
    - script: Script code for language variants (optional)
226
    - region: Region code for localization (optional)
227
    
228
    Returns:
229
    Carrier name string, empty if unavailable or not applicable
230
    """
231

232
def name_for_valid_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
233
    """
234
    Get carrier name, assuming number is already validated.
235
    
236
    Parameters:
237
    - numobj: Valid PhoneNumber to get carrier for
238
    - lang: Language code for carrier name
239
    - script: Script code for language variants (optional)
240
    - region: Region code for localization (optional)
241
    
242
    Returns:
243
    Carrier name string
244
    """
245

246
def safe_display_name(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
247
    """
248
    Get carrier name safe for display (empty string if unavailable).
249
    
250
    Parameters:
251
    - numobj: PhoneNumber to get carrier for
252
    - lang: Language code for carrier name
253
    - script: Script code for language variants (optional)
254
    - region: Region code for localization (optional)
255
    
256
    Returns:
257
    Carrier name string or empty string if not available
258
    """
259
```
260

261
**Usage Examples:**
262

263
```python
264
# Import carrier functions
265
from phonenumbers import carrier
266

267
# Get carrier information for mobile numbers
268
mobile_phone = phonenumbers.parse("+447700123456")  # UK mobile
269
carrier_name = carrier.name_for_number(mobile_phone, "en")  # "Vodafone" (example)
270

271
# Different languages
272
carrier_fr = carrier.name_for_number(mobile_phone, "fr")
273

274
# Safe display (won't raise exceptions)
275
display_name = carrier.safe_display_name(mobile_phone, "en")
276

277
# For landlines, carrier info is typically empty
278
landline = phonenumbers.parse("+442083661177")
279
landline_carrier = carrier.name_for_number(landline, "en")  # ""
280

281
# US mobile example
282
us_mobile = phonenumbers.parse("+15551234567")
283
us_carrier = carrier.name_for_number(us_mobile, "en")  # "Verizon" (example)
284
```
285

286
### Timezone Services
287

288
Functions to determine possible timezones for phone numbers.
289

290
```python { .api }
291
def time_zones_for_number(numobj: PhoneNumber) -> tuple[str, ...]:
292
    """
293
    Get possible time zones for a phone number.
294
    
295
    Parameters:
296
    - numobj: PhoneNumber to get timezones for
297
    
298
    Returns:
299
    Tuple of timezone identifiers (e.g., "America/New_York", "Europe/London")
300
    """
301

302
def time_zones_for_geographical_number(numobj: PhoneNumber) -> tuple[str, ...]:
303
    """
304
    Get time zones for geographical numbers only.
305
    
306
    Parameters:
307
    - numobj: Geographical PhoneNumber
308
    
309
    Returns:
310
    Tuple of timezone identifiers for geographical numbers
311
    """
312
```
313

314
**Timezone Constants:**
315

316
```python { .api }
317
UNKNOWN_TIMEZONE: str  # Constant for unknown timezone
318
```
319

320
**Usage Examples:**
321

322
```python
323
# Import timezone functions
324
from phonenumbers import timezone
325

326
# Get timezones for numbers
327
uk_phone = phonenumbers.parse("+442083661177")
328
uk_timezones = timezone.time_zones_for_number(uk_phone)  # ("Europe/London",)
329

330
us_phone = phonenumbers.parse("+12125551234")  # New York
331
us_timezones = timezone.time_zones_for_number(us_phone)  # ("America/New_York",)
332

333
# Some regions may have multiple timezones
334
russia_phone = phonenumbers.parse("+74951234567")  # Moscow area
335
russia_timezones = timezone.time_zones_for_number(russia_phone)
336

337
# For geographical numbers only
338
geo_timezones = timezone.time_zones_for_geographical_number(uk_phone)
339

340
# Handle unknown timezones
341
if not uk_timezones or uk_timezones[0] == timezone.UNKNOWN_TIMEZONE:
342
    print("Timezone information not available")
343
else:
344
    print(f"Timezone: {uk_timezones[0]}")
345

346
# Working with timezone information
347
import datetime
348
import pytz
349

350
if uk_timezones:
351
    tz = pytz.timezone(uk_timezones[0])
352
    local_time = datetime.datetime.now(tz)
353
    print(f"Local time in {uk_timezones[0]}: {local_time}")
354
```
355

356
### Regional Information and Capabilities
357

358
Functions to get information about supported regions and their capabilities.
359

360
```python { .api }
361
def supported_calling_codes() -> set[int]:
362
    """
363
    Get set of all supported country calling codes.
364
    
365
    Returns:
366
    Set of supported country calling codes
367
    """
368

369
def supported_types_for_region(region_code: str) -> set[int]:
370
    """
371
    Get supported phone number types for region.
372
    
373
    Parameters:
374
    - region_code: Region identifier
375
    
376
    Returns:
377
    Set of PhoneNumberType values supported in the region
378
    """
379

380
def supported_types_for_non_geo_entity(country_code: int) -> set[int]:
381
    """
382
    Get supported types for non-geographical entities.
383
    
384
    Parameters:
385
    - country_code: Non-geographical country code
386
    
387
    Returns:
388
    Set of supported PhoneNumberType values
389
    """
390

391
def is_nanpa_country(region_code: str) -> bool:
392
    """
393
    Check if region is part of North American Numbering Plan (NANPA).
394
    
395
    Parameters:
396
    - region_code: Region identifier
397
    
398
    Returns:
399
    True if region uses NANPA numbering
400
    """
401

402
def is_mobile_number_portable_region(region_code: str) -> bool:
403
    """
404
    Check if mobile number portability is supported in region.
405
    
406
    Parameters:
407
    - region_code: Region identifier
408
    
409
    Returns:
410
    True if mobile numbers can be ported between carriers
411
    """
412
```
413

414
**Usage Examples:**
415

416
```python
417
# Get all supported country codes
418
all_codes = phonenumbers.supported_calling_codes()  # {1, 7, 20, 27, 30, ...}
419

420
# Check what number types are supported in a region
421
uk_types = phonenumbers.supported_types_for_region("GB")
422
# {PhoneNumberType.FIXED_LINE, PhoneNumberType.MOBILE, PhoneNumberType.TOLL_FREE, ...}
423

424
us_types = phonenumbers.supported_types_for_region("US")
425

426
# Check NANPA membership
427
is_us_nanpa = phonenumbers.is_nanpa_country("US")  # True
428
is_uk_nanpa = phonenumbers.is_nanpa_country("GB")  # False
429

430
# Check mobile number portability
431
us_portable = phonenumbers.is_mobile_number_portable_region("US")  # True
432
some_portable = phonenumbers.is_mobile_number_portable_region("XX")  # False
433

434
# Working with supported types
435
if phonenumbers.PhoneNumberType.MOBILE in uk_types:
436
    print("UK supports mobile numbers")
437

438
if phonenumbers.PhoneNumberType.PREMIUM_RATE in us_types:
439
    print("US supports premium rate numbers")
440
```
441

442
### International Services
443

444
Functions for international dialing and cross-border calling.
445

446
```python { .api }
447
def can_be_internationally_dialled(numobj: PhoneNumber) -> bool:
448
    """
449
    Check if number can be dialed internationally.
450
    
451
    Parameters:
452
    - numobj: PhoneNumber to check
453
    
454
    Returns:
455
    True if the number can be called from other countries
456
    """
457

458
def ndd_prefix_for_region(region_code: str, strip_non_digits: bool) -> str | None:
459
    """
460
    Get national direct dialing prefix for region.
461
    
462
    Parameters:
463
    - region_code: Region identifier
464
    - strip_non_digits: Whether to remove non-digit characters
465
    
466
    Returns:
467
    National dialing prefix (e.g., "0" for UK) or None
468
    """
469

470
def country_mobile_token(country_code: int) -> str:
471
    """
472
    Get mobile token for country (used in some countries when calling mobiles).
473
    
474
    Parameters:
475
    - country_code: Country calling code
476
    
477
    Returns:
478
    Mobile token string, empty if not applicable
479
    """
480
```
481

482
**Usage Examples:**
483

484
```python
485
# Check international dialing capability
486
uk_phone = phonenumbers.parse("+442083661177")
487
can_dial_intl = phonenumbers.can_be_internationally_dialled(uk_phone)  # True
488

489
# Some numbers may not be internationally dialable (e.g., emergency, short codes)
490
emergency = phonenumbers.parse("911", "US")
491
can_dial_911 = phonenumbers.can_be_internationally_dialled(emergency)  # False
492

493
# Get national dialing prefixes
494
uk_prefix = phonenumbers.ndd_prefix_for_region("GB", True)  # "0"
495
us_prefix = phonenumbers.ndd_prefix_for_region("US", True)  # "1"
496

497
# Mobile tokens (used in some countries)
498
mobile_token = phonenumbers.country_mobile_token(39)  # Italy example
499

500
# Practical usage for international calling
501
def format_for_international_call(phone, calling_from_region):
502
    if phonenumbers.can_be_internationally_dialled(phone):
503
        return phonenumbers.format_out_of_country_calling_number(phone, calling_from_region)
504
    else:
505
        return "Cannot be dialed internationally"
506

507
intl_format = format_for_international_call(uk_phone, "US")
508
# "011 44 20 8366 1177"
509
```