0
# Short Numbers
1

2
Specialized handling for short dialing codes including emergency numbers, service numbers, and premium rate numbers. Short numbers are typically 3-6 digit codes that provide access to specific services and may have regional variations in availability and cost.
3

4
## Capabilities
5

6
### Short Number Validation
7

8
Functions to validate short numbers and check their applicability in different regions.
9

10
```python { .api }
11
def is_possible_short_number(numobj: PhoneNumber) -> bool:
12
    """
13
    Check if short number is possible.
14
    
15
    Parameters:
16
    - numobj: PhoneNumber representing a short number
17
    
18
    Returns:
19
    True if the number could be a valid short number
20
    """
21

22
def is_possible_short_number_for_region(short_numobj: PhoneNumber, region_dialing_from: str) -> bool:
23
    """
24
    Check if short number is possible when dialing from specified region.
25
    
26
    Parameters:
27
    - short_numobj: PhoneNumber representing a short number
28
    - region_dialing_from: Region code from which the number would be dialed
29
    
30
    Returns:
31
    True if the short number is possible from the specified region
32
    """
33

34
def is_valid_short_number(numobj: PhoneNumber) -> bool:
35
    """
36
    Check if short number is valid.
37
    
38
    Parameters:  
39
    - numobj: PhoneNumber representing a short number
40
    
41
    Returns:
42
    True if the short number is valid and operational
43
    """
44

45
def is_valid_short_number_for_region(short_numobj: PhoneNumber, region_dialing_from: str) -> bool:
46
    """
47
    Check if short number is valid for specified region.
48
    
49
    Parameters:
50
    - short_numobj: PhoneNumber representing a short number
51
    - region_dialing_from: Region code from which the number would be dialed
52
    
53
    Returns:
54
    True if the short number is valid when dialed from the specified region
55
    """
56
```
57

58
**Usage Examples:**
59

60
```python
61
# Parse short numbers (typically without country codes)
62
emergency_us = phonenumbers.parse("911", "US")
63
emergency_uk = phonenumbers.parse("999", "GB")
64
directory_us = phonenumbers.parse("411", "US")
65

66
# Check if short numbers are possible
67
is_911_possible = phonenumbers.is_possible_short_number(emergency_us)  # True
68
is_999_possible = phonenumbers.is_possible_short_number(emergency_uk)  # True
69

70
# Check validity in specific regions
71
is_911_valid_us = phonenumbers.is_valid_short_number_for_region(emergency_us, "US")  # True
72
is_911_valid_uk = phonenumbers.is_valid_short_number_for_region(emergency_us, "GB")  # False
73

74
is_999_valid_uk = phonenumbers.is_valid_short_number_for_region(emergency_uk, "GB")  # True
75
is_999_valid_us = phonenumbers.is_valid_short_number_for_region(emergency_uk, "US")  # False
76

77
# General validation
78
is_411_valid = phonenumbers.is_valid_short_number(directory_us)  # True
79

80
# International short number example
81
international_toll_free = phonenumbers.parse("800", None)  # Some international codes
82
is_possible_intl = phonenumbers.is_possible_short_number(international_toll_free)
83
```
84

85
### Emergency Number Services
86

87
Specialized functions for identifying and validating emergency service numbers.
88

89
```python { .api }
90
def is_emergency_number(number: str, region_code: str) -> bool:
91
    """
92
    Check if number is an emergency number in given region.
93
    
94
    Parameters:
95
    - number: Phone number string to check
96
    - region_code: Region code for emergency number context
97
    
98
    Returns:
99
    True if the number is recognized as an emergency number in the region
100
    """
101

102
def connects_to_emergency_number(number: str, region_code: str) -> bool:
103
    """
104
    Check if number connects to emergency services.
105
    
106
    Parameters:
107
    - number: Phone number string to check
108
    - region_code: Region code for emergency service context
109
    
110
    Returns:
111
    True if dialing the number would connect to emergency services
112
    """
113
```
114

115
**Usage Examples:**
116

117
```python
118
# Check emergency numbers for different regions
119
is_911_emergency_us = phonenumbers.is_emergency_number("911", "US")  # True
120
is_112_emergency_us = phonenumbers.is_emergency_number("112", "US")  # True (also works in US)
121
is_999_emergency_uk = phonenumbers.is_emergency_number("999", "GB")  # True
122
is_112_emergency_uk = phonenumbers.is_emergency_number("112", "GB")  # True
123

124
# Check if numbers connect to emergency services
125
connects_911 = phonenumbers.connects_to_emergency_number("911", "US")  # True
126
connects_999 = phonenumbers.connects_to_emergency_number("999", "GB")  # True
127

128
# Invalid emergency numbers
129
is_123_emergency = phonenumbers.is_emergency_number("123", "US")  # False
130

131
# Multi-regional emergency codes
132
is_112_emergency_de = phonenumbers.is_emergency_number("112", "DE")  # True (EU standard)
133
is_112_emergency_fr = phonenumbers.is_emergency_number("112", "FR")  # True
134

135
# Practical usage: emergency number detection
136
def is_emergency_call(number_str, region):
137
    """Helper function to identify emergency calls."""
138
    return (phonenumbers.is_emergency_number(number_str, region) or 
139
            phonenumbers.connects_to_emergency_number(number_str, region))
140

141
# Test various emergency scenarios
142
print(is_emergency_call("911", "US"))   # True
143
print(is_emergency_call("112", "DE"))   # True  
144
print(is_emergency_call("100", "IN"))   # True (police in India)
145
print(is_emergency_call("123", "US"))   # False
146
```
147

148
### Short Number Cost Information
149

150
Functions to determine the cost category and billing implications of short numbers.
151

152
```python { .api }
153
def expected_cost(numobj: PhoneNumber) -> int:
154
    """
155
    Get expected cost category for short number.
156
    
157
    Parameters:
158
    - numobj: PhoneNumber representing a short number
159
    
160
    Returns:
161
    ShortNumberCost value indicating cost category
162
    """
163

164
def expected_cost_for_region(short_numobj: PhoneNumber, region_dialing_from: str) -> int:
165
    """
166
    Get expected cost when dialing from specified region.
167
    
168
    Parameters:
169
    - short_numobj: PhoneNumber representing a short number
170
    - region_dialing_from: Region code from which the number would be dialed
171
    
172
    Returns:
173
    ShortNumberCost value for the specific dialing region
174
    """
175
```
176

177
**Short Number Cost Types:**
178

179
```python { .api }
180
class ShortNumberCost:
181
    """Cost categories for short numbers."""
182
    TOLL_FREE = 0      # Free to call
183
    STANDARD_RATE = 1  # Standard local/national rate
184
    PREMIUM_RATE = 2   # Higher than standard rate
185
    UNKNOWN_COST = -1  # Cost information unavailable
186
```
187

188
**Usage Examples:**
189

190
```python
191
# Check costs for different short numbers
192
emergency = phonenumbers.parse("911", "US")
193
directory = phonenumbers.parse("411", "US")
194
premium = phonenumbers.parse("900", "US")  # Premium rate example
195

196
# Get cost categories
197
emergency_cost = phonenumbers.expected_cost(emergency)
198
directory_cost = phonenumbers.expected_cost(directory)
199
premium_cost = phonenumbers.expected_cost(premium)
200

201
# Interpret cost categories
202
if emergency_cost == phonenumbers.ShortNumberCost.TOLL_FREE:
203
    print("Emergency calls are free")
204
elif emergency_cost == phonenumbers.ShortNumberCost.STANDARD_RATE:
205
    print("Emergency calls charged at standard rate")
206

207
# Regional cost variations
208
uk_directory = phonenumbers.parse("118", "GB")
209
uk_cost = phonenumbers.expected_cost_for_region(uk_directory, "GB")
210

211
# Cost checking utility
212
def describe_cost(short_number, region=None):
213
    """Describe the cost implications of calling a short number."""
214
    if region:
215
        cost = phonenumbers.expected_cost_for_region(short_number, region)
216
    else:
217
        cost = phonenumbers.expected_cost(short_number)
218
    
219
    cost_descriptions = {
220
        phonenumbers.ShortNumberCost.TOLL_FREE: "Free to call",
221
        phonenumbers.ShortNumberCost.STANDARD_RATE: "Standard rate applies", 
222
        phonenumbers.ShortNumberCost.PREMIUM_RATE: "Premium rate - higher charges apply",
223
        phonenumbers.ShortNumberCost.UNKNOWN_COST: "Cost information unavailable"
224
    }
225
    
226
    return cost_descriptions.get(cost, "Unknown cost category")
227

228
# Usage examples
229
print(describe_cost(emergency))  # "Free to call"
230
print(describe_cost(directory))  # "Standard rate applies"
231
print(describe_cost(premium))    # "Premium rate - higher charges apply"
232
```
233

234
### Carrier-Specific Short Numbers
235

236
Functions to identify short numbers that are specific to particular mobile carriers.
237

238
```python { .api }
239
def is_carrier_specific(numobj: PhoneNumber) -> bool:
240
    """
241
    Check if short number is carrier-specific.
242
    
243
    Parameters:
244
    - numobj: PhoneNumber representing a short number
245
    
246
    Returns:
247
    True if the short number only works with specific carriers
248
    """
249

250
def is_carrier_specific_for_region(numobj: PhoneNumber, region_dialing_from: str) -> bool:
251
    """
252
    Check if short number is carrier-specific for region.
253
    
254
    Parameters:
255
    - numobj: PhoneNumber representing a short number
256
    - region_dialing_from: Region code for carrier context
257
    
258
    Returns:
259
    True if the short number is carrier-specific in the specified region
260
    """
261
```
262

263
**Usage Examples:**
264

265
```python
266
# Some short numbers work only with specific carriers
267
carrier_service = phonenumbers.parse("611", "US")  # Customer service (carrier-specific)
268
universal_service = phonenumbers.parse("911", "US")  # Emergency (universal)
269

270
# Check carrier specificity
271
is_611_carrier_specific = phonenumbers.is_carrier_specific(carrier_service)  # True
272
is_911_carrier_specific = phonenumbers.is_carrier_specific(universal_service)  # False
273

274
# Regional carrier specificity
275
is_carrier_specific_us = phonenumbers.is_carrier_specific_for_region(carrier_service, "US")
276

277
# Practical usage
278
def check_service_availability(short_number, region):
279
    """Check if a short number service is universally available."""
280
    if phonenumbers.is_carrier_specific_for_region(short_number, region):
281
        return "Service may not be available on all carriers"
282
    else:
283
        return "Service should work on all carriers"
284

285
availability = check_service_availability(carrier_service, "US")
286
print(availability)  # "Service may not be available on all carriers"
287
```
288

289
### SMS and Messaging Services
290

291
Functions to identify short numbers that provide SMS or messaging services.
292

293
```python { .api }
294
def is_sms_service_for_region(numobj: PhoneNumber, region_dialing_from: str) -> bool:
295
    """
296
    Check if number is an SMS service in specified region.
297
    
298
    Parameters:
299
    - numobj: PhoneNumber representing a short number
300
    - region_dialing_from: Region code for SMS service context
301
    
302
    Returns:
303
    True if the number provides SMS services in the specified region
304
    """
305
```
306

307
**Usage Examples:**
308

309
```python
310
# Check for SMS services
311
sms_service = phonenumbers.parse("40404", "US")  # Twitter SMS (example)
312
voice_service = phonenumbers.parse("411", "US")   # Directory assistance
313

314
# Check if services support SMS
315
is_sms = phonenumbers.is_sms_service_for_region(sms_service, "US")     # True
316
is_voice_sms = phonenumbers.is_sms_service_for_region(voice_service, "US")  # False
317

318
# Practical usage for messaging applications
319
def get_service_type(short_number, region):
320
    """Determine what type of service a short number provides."""
321
    services = []
322
    
323
    if phonenumbers.is_sms_service_for_region(short_number, region):
324
        services.append("SMS")
325
    
326
    if phonenumbers.is_emergency_number(
327
        phonenumbers.format_number(short_number, phonenumbers.PhoneNumberFormat.E164),
328
        region
329
    ):
330
        services.append("Emergency")
331
    
332
    if phonenumbers.is_carrier_specific_for_region(short_number, region):
333
        services.append("Carrier-specific")
334
    
335
    return services if services else ["Voice service"]
336

337
service_types = get_service_type(sms_service, "US")
338
print(service_types)  # ["SMS"]
339
```
340

341
### Regional Short Number Support
342

343
Information about which regions support short number services.
344

345
```python { .api }
346
SUPPORTED_SHORT_REGIONS: list[str]  # List of regions with short number support
347
```
348

349
**Usage Examples:**
350

351
```python
352
# Check which regions have short number support
353
supported = phonenumbers.SUPPORTED_SHORT_REGIONS
354

355
# Check if a specific region is supported
356
is_us_supported = "US" in supported  # True
357
is_gb_supported = "GB" in supported  # True
358

359
# Validate region before processing short numbers
360
def process_short_number(number_str, region):
361
    """Process a short number with region validation."""
362
    if region not in phonenumbers.SUPPORTED_SHORT_REGIONS:
363
        return f"Short number support not available for region: {region}"
364
    
365
    try:
366
        short_number = phonenumbers.parse(number_str, region)
367
        
368
        if phonenumbers.is_valid_short_number_for_region(short_number, region):
369
            cost = phonenumbers.expected_cost_for_region(short_number, region)
370
            is_emergency = phonenumbers.is_emergency_number(number_str, region)
371
            
372
            result = {
373
                "valid": True,
374
                "cost_category": cost,
375
                "is_emergency": is_emergency,
376
                "carrier_specific": phonenumbers.is_carrier_specific_for_region(short_number, region)
377
            }
378
            return result
379
        else:
380
            return {"valid": False, "reason": "Invalid short number for region"}
381
            
382
    except phonenumbers.NumberParseException as e:
383
        return {"valid": False, "reason": f"Parsing error: {e}"}
384

385
# Usage examples
386
result_911 = process_short_number("911", "US")
387
# {"valid": True, "cost_category": 0, "is_emergency": True, "carrier_specific": False}
388

389
result_611 = process_short_number("611", "US") 
390
# {"valid": True, "cost_category": 1, "is_emergency": False, "carrier_specific": True}
391

392
print(f"Supported regions: {len(supported)} regions")
393
print(f"Sample regions: {supported[:10]}")  # First 10 supported regions
394
```
395

396
### Advanced Short Number Operations
397

398
Combining multiple short number functions for comprehensive analysis.
399

400
**Usage Examples:**
401

402
```python
403
def analyze_short_number(number_str, region):
404
    """Comprehensive analysis of a short number."""
405
    if region not in phonenumbers.SUPPORTED_SHORT_REGIONS:
406
        return {"error": f"Region {region} not supported for short numbers"}
407
    
408
    try:
409
        short_number = phonenumbers.parse(number_str, region)
410
        
411
        analysis = {
412
            "number": number_str,
413
            "region": region,
414
            "is_possible": phonenumbers.is_possible_short_number_for_region(short_number, region),
415
            "is_valid": phonenumbers.is_valid_short_number_for_region(short_number, region),
416
            "is_emergency": phonenumbers.is_emergency_number(number_str, region),
417
            "connects_to_emergency": phonenumbers.connects_to_emergency_number(number_str, region),
418
            "cost_category": phonenumbers.expected_cost_for_region(short_number, region),
419
            "is_carrier_specific": phonenumbers.is_carrier_specific_for_region(short_number, region),
420
            "is_sms_service": phonenumbers.is_sms_service_for_region(short_number, region)
421
        }
422
        
423
        # Add cost description
424
        cost_map = {
425
            phonenumbers.ShortNumberCost.TOLL_FREE: "Free",
426
            phonenumbers.ShortNumberCost.STANDARD_RATE: "Standard rate",
427
            phonenumbers.ShortNumberCost.PREMIUM_RATE: "Premium rate",
428
            phonenumbers.ShortNumberCost.UNKNOWN_COST: "Unknown cost"
429
        }
430
        analysis["cost_description"] = cost_map.get(analysis["cost_category"], "Unknown")
431
        
432
        return analysis
433
        
434
    except phonenumbers.NumberParseException as e:
435
        return {"error": f"Failed to parse '{number_str}': {e}"}
436

437
# Analyze various short numbers
438
emergency_analysis = analyze_short_number("911", "US")
439
directory_analysis = analyze_short_number("411", "US")
440
uk_emergency_analysis = analyze_short_number("999", "GB")
441

442
print("911 Analysis:", emergency_analysis)
443
# Output includes: is_emergency=True, cost="Free", carrier_specific=False
444

445
print("411 Analysis:", directory_analysis)  
446
# Output includes: is_emergency=False, cost="Standard rate", etc.
447

448
# Batch analysis
449
short_numbers_to_test = [
450
    ("911", "US"), ("999", "GB"), ("112", "DE"), 
451
    ("411", "US"), ("118", "GB"), ("611", "US")
452
]
453

454
for number, region in short_numbers_to_test:
455
    result = analyze_short_number(number, region)
456
    if "error" not in result:
457
        print(f"{number} ({region}): {'Emergency' if result['is_emergency'] else 'Service'} "
458
              f"- {result['cost_description']}")
459
```