Developing an application that handles Guam phone numbers? This comprehensive guide covers everything developers need to know about the Guam phone number system, including the 671 area code, NANP integration, validation techniques, and number portability. You'll learn how to validate Guam phone numbers programmatically, understand dialing procedures, implement number porting, and follow telecommunications best practices for the U.S. territory.
Background: Guam's Telecommunications Landscape and Area Code 671
NANP Integration and Regulatory Framework
Guam's telecommunications system is deeply integrated with the North American Numbering Plan (NANP), a testament to its status as a U.S. territory. This integration, finalized in 1997, simplified communication with North America and brought Guam into a standardized numbering system. The Federal Communications Commission (FCC) maintains regulatory oversight over Guam telecommunications under Title 47 of the U.S. Code, ensuring compliance with federal telecommunications regulations.
Practical Implications for Developers:
Domestic Routing: Calls between Guam and the U.S. mainland are treated as domestic within the NANP, avoiding international gateway routing
Rate Treatment: No international dialing prefixes required; standard NANP long-distance rates apply
Database Integration: Guam numbers participate in shared NANP databases including NPAC (Number Portability Administration Center) and LNP (Local Number Portability)
Compliance Requirements: Applications must adhere to FCC regulations including TCPA (Telephone Consumer Protection Act) for automated dialing and TRACED Act requirements for caller ID authentication
Regulatory Authority:
FCC: Primary federal regulator for interstate and international communications
Guam Public Utilities Commission (PUC): Local regulatory body for intra-territory services
NANPA: North American Numbering Plan Administrator manages number allocation and central office code assignments
Before 1997 integration, as detailed in historical accounts from the Guam Recorder, calling the U.S. mainland involved international dialing procedures and significantly higher costs, impacting communication with family and businesses.
Guam Phone Number Structure: Understanding the 671 Area Code Format
Guam phone numbers adhere to the NANP structure, making them easy to integrate into applications designed for North American numbers. Here's the breakdown:
Core Components
Component
Value
Description
Country Code
+1
Shared with other NANP members
Area Code
671
Unique to Guam
Subscriber Number
7 digits
Local phone number (NXX-XXXX)
Total Length
10 digits (national)
12 digits (international with +1)
Format Variations and Examples
While the basic structure remains consistent, you'll encounter variations based on the service type:
Type
Format
Example
Usage
Landline
+1 671 NXX XXXX
+1 671 472 1234
Fixed location services
Mobile
+1 671 NXX XXXX
+1 671 988 5678
Cellular services
Toll-Free
+1 800 XXX XXXX
+1 800 234 5678
No-cost calling
Premium Rate
+1 900 XXX XXXX
+1 900 345 6789
Pay-per-call services
Note on Line Type Detection: Unlike some countries with dedicated mobile prefixes, NANP does not distinguish landline from mobile at the number level. Programmatic detection requires querying carrier databases or using specialized APIs like CNAM (Caller Name) lookup services or HLR (Home Location Register) lookups that return line type information.
NXX Exchange Code Rules and Restrictions
Key Point:N represents digits 2–9 (excluding 0 and 1), while X can be any digit 0–9. This distinction is crucial for accurate validation.
Reserved and Restricted NXX Codes:
N11 Codes: Reserved for special services (211-information, 311-non-emergency, 411-directory, 511-traffic, 611-repair, 711-relay, 811-utilities, 911-emergency)
555-01XX: Reserved for fictional use in media and testing (555-0100 through 555-0199)
555-XXXX: Mostly reserved except 555-0100 to 555-0199 for actual directory assistance in some areas
958/959 Prefixes: Often used for carrier network testing and should be blocked from customer assignment
NPA-555-1212: Standard directory assistance format across NANP
Prohibited Formats: NXX cannot be N00 or N11 where N = 2–9
Valid NXX Pattern:[2-9][0-8][0-9] or [2-9][0-9][0-9] excluding the specific reserved patterns listed above.
How to Validate Guam Phone Numbers: Ensuring Data Integrity
Robust validation is essential for any application handling phone numbers. While regular expressions provide basic validation, production applications should use comprehensive libraries.
Regex Patterns for Guam Numbers
Here are regex patterns with comprehensive edge case handling:
JavaScript
// Basic Guam number validation (international format)const guamRegex = /^\+1\s671\s[2-9][0-9]{2}\s[0-9]{4}$/;
// Extended validation with optional formatting (handles spaces, hyphens, parentheses)const extendedRegex = /^\+?1?\s*\(?671\)?[-.\s]?[2-9]\d{2}[-.\s]?\d{4}$/;
// Comprehensive validation excluding reserved rangesconst comprehensiveRegex = /^\+?1?\s*\(?671\)?[-.\s]?(?!555(?:01[0-9][0-9])|[2-9]11)([2-9]\d{2})[-.\s]?\d{4}$/;
// Usage example with error handlingfunctionvalidateGuamNumber(phoneNumber) {
if (!phoneNumber || typeof phoneNumber !== 'string') {
return { valid: false, error: 'Invalid input type' };
}
const isValid = extendedRegex.test(phoneNumber);
if (!isValid) {
return { valid: false, error: 'Number does not match Guam format' };
}
// Check for reserved rangesconst digits = phoneNumber.replace(/\D/g, '');
const exchange = digits.substr(4, 3);
if (exchange.match(/^[2-9]11$/)) {
return { valid: false, error: 'Reserved N11 service code' };
}
return { valid: true, normalized: `+1671${digits.substr(-7)}` };
}
Production-Ready Validation Libraries
For production applications, use battle-tested validation libraries instead of custom regex:
Language Support: Java (original), JavaScript, C++, Python, and 20+ community ports
Key Features: Parse, format, validate phone numbers for 250+ countries; detect number type (mobile, landline, toll-free); carrier and timezone detection
Dialing Procedures: How to Call Guam Phone Numbers
Understanding dialing procedures is crucial for applications that initiate or process calls. Here are the variations for domestic and international calls.
Domestic Calls within Guam
Local Calls: Dial the 7-digit subscriber number (XXX-XXXX).
Mobile-to-Mobile/Landline-to-Mobile: Dial 1 + 671 + the 7-digit number. The "1" signifies a domestic long-distance call within the NANP.
International Calls and Rate Information
Outbound from Guam: Dial 011 (international prefix) + Country Code + Number.
Inbound to Guam: Dial +1 671 + Local Number. The "+1" clearly identifies Guam within the NANP.
Cost Implications:
Calls to/from U.S. Mainland: Treated as domestic long-distance; rates typically $0.05–$0.15 per minute depending on carrier and plan
International Calls from Guam: Standard international rates apply; vary by destination country ($0.10–$3.00+ per minute)
Rate Zone Classification: Guam is classified as NANP Zone 1, same as U.S., Canada, and Caribbean territories
VoIP Considerations: Internet-based calling (WhatsApp, Skype, etc.) may bypass traditional telecom rates entirely
Important for Developers: Applications that bill for call services must clearly disclose rate information and obtain user consent per FCC TCPA requirements.
Guam Number Portability: How to Port Phone Numbers Between Carriers
Number portability allows users to retain their numbers when switching carriers. This adds complexity for developers, but it's a crucial aspect of modern telecommunications. As documented by the FCC in DA 05-2714, Guam's implementation of wireless number portability has faced challenges due to infrastructure dependencies and coordination between carriers.
Porting Process and Implementation
The porting process involves several steps, including customer requests, carrier verification, and database updates. You'll need to integrate with number portability databases and handle potential delays or errors.
Key Considerations:
Real-time NPAC Integration: Connect to the Number Portability Administration Center (NPAC) database for accurate porting information.
Automated Validation: Implement automated communication between carriers for efficient verification.
Standardized Request Handling: Use Local Service Request (LSR) forms for consistent processing.
Emergency Services Routing: Ensure emergency services are correctly routed during and after the porting process.
Porting Timeline Standards and Implementation Example
Porting timelines vary based on the complexity of the request:
Port Type
Maximum Duration
Validation Fields
Simple
1 business day
4 fields max
Complex
4 business days
Additional verification
Emergency
4 hours
Expedited process
JavaScript
// Example Number Portability Validation with comprehensive error handlingfunctionvalidatePortingRequest(request) {
const requiredFields = ["accountNumber", "pin", "zipCode", "lastFourSSN"];
const errors = [];
// Check required fields
requiredFields.forEach(field => {
if (!request.hasOwnProperty(field) || !request[field]) {
errors.push(`Missing required field: ${field}`);
}
});
// Validate phone number formatif (!request.phoneNumber || !validateGuamNumber(request.phoneNumber).valid) {
errors.push("Invalid phone number format");
}
// Validate account number (typically alphanumeric, 6-20 characters)if (request.accountNumber && !/^[A-Z0-9]{6,20}$/i.test(request.accountNumber)) {
errors.push("Invalid account number format");
}
// Validate PIN (typically 4-6 digits)if (request.pin && !/^\d{4,6}$/.test(request.pin)) {
errors.push("Invalid PIN format (must be 4-6 digits)");
}
// Validate ZIP code (5 or 9 digits)if (request.zipCode && !/^\d{5}(-\d{4})?$/.test(request.zipCode)) {
errors.push("Invalid ZIP code format");
}
return {
valid: errors.length === 0,
errors: errors
};
}
Common Porting Error Codes and Failure Scenarios
Understanding error codes helps implement robust retry and user notification logic:
Error Code
Description
Resolution
E1001
Invalid account number
Verify account details with old carrier; user must provide correct account number
E1002
PIN/Password mismatch
User must confirm PIN/password; may need to reset with current carrier
E1003
Address mismatch
Billing address must match carrier records; update with current carrier first
E1004
Number not portable
Number may be landline-only or in contract; contact current carrier
E1005
Port already in progress
Wait for current port to complete (typically 1–4 days)
E1006
CSR (Customer Service Record) mismatch
Customer info doesn't match carrier database; verify all details
E2001
NPAC database timeout
Temporary issue; retry after 15–30 minutes
E2002
Carrier system unavailable
Wait for carrier system maintenance to complete; retry in 1–4 hours
E3001
Duplicate port request
Port already completed or request submitted twice
E3002
FOC (Firm Order Commitment) date conflict
Requested activation date unavailable; select alternate date
API Integration Considerations: Contact carrier business departments for sandbox access, rate limits typically 100–1000 requests/hour depending on service tier
Technical Implementation: Best Practices for Guam Phone Number Integration
Following best practices ensures your application is robust, reliable, and compliant with industry standards.
E.164 Compliance: The Global Standard
The E.164 format is the international standard for phone numbers. Always store numbers in this format (+1671XXXXXXX) for consistency and interoperability.
Normalization Examples:
Python
import re
defnormalize_to_e164(phone_number):
"""Convert various Guam number formats to E.164 standard."""# Remove all non-digit characters
digits = re.sub(r'\D', '', phone_number)
# Handle different input lengthsiflen(digits) == 7:
# Local format: add country code and area codereturnf'+1671{digits}'eliflen(digits) == 10and digits.startswith('671'):
# National format: add country codereturnf'+1{digits}'eliflen(digits) == 11and digits.startswith('1671'):
# NANP format: add + prefixreturnf'+{digits}'eliflen(digits) == 11and digits.startswith('1'):
# Check if it's a Guam numberif digits[1:4] == '671':
returnf'+{digits}'# Already in potential E.164 format or invalidreturnNonedefvalidate_e164(phone_number):
"""Validate E.164 format for Guam numbers."""
pattern = r'^\+1671[2-9]\d{6}$'returnbool(re.match(pattern, phone_number))
# Example usage
examples = [
'4721234', # Local format'671-472-1234', # National format with hyphens'(671) 472-1234', # National format with parentheses'1-671-472-1234', # NANP format'+1 671 472 1234'# E.164 with spaces
]
for example in examples:
normalized = normalize_to_e164(example)
if normalized and validate_e164(normalized):
print(f'✓ {example:20} → {normalized}')
else:
print(f'✗ {example:20} → Invalid')
JavaScript
// JavaScript normalization examplefunctionnormalizeToE164(phoneNumber) {
// Remove all non-digit charactersconst digits = phoneNumber.replace(/\D/g, '');
// Handle different input lengthsif (digits.length === 7) {
// Local format: add country code and area codereturn`+1671${digits}`;
} elseif (digits.length === 10 && digits.startsWith('671')) {
// National format: add country codereturn`+1${digits}`;
} elseif (digits.length === 11 && digits.startsWith('1671')) {
// NANP format: add + prefixreturn`+${digits}`;
}
// Already in potential E.164 format or invalidreturnnull;
}
functionformatForDisplay(e164Number, locale = 'en-US') {
// Format E.164 number for user-friendly displayconst match = e164Number.match(/^\+1(\d{3})(\d{3})(\d{4})$/);
if (!match) return e164Number;
const [, area, prefix, line] = match;
// Return formatted based on locale preferencereturn`(${area}) ${prefix}-${line}`;
}
// Example usageconst input = '671-472-1234';
const e164 = normalizeToE164(input);
const display = formatForDisplay(e164);
console.log(`Input: ${input}`);
console.log(`E.164: ${e164}`);
console.log(`Display: ${display}`);
Integration Best Practices
Consistent Formatting: Store numbers in E.164 format, but format them appropriately for display based on user locale.
Thorough Porting Validation: Validate all porting requests against the NPAC database and implement retry logic for failed queries.
Comprehensive Error Handling: Log all porting transactions and maintain audit trails for compliance.
Database Schema and Performance Optimization
Recommended Database Schema:
SQL
CREATE TABLE phone_numbers (
id UUID PRIMARY KEYDEFAULT gen_random_uuid(),
e164_number VARCHAR(15) NOT NULLUNIQUE,
country_code VARCHAR(3) NOT NULLDEFAULT'GU',
area_code VARCHAR(3) NOT NULL,
subscriber_number VARCHAR(7) NOT NULL,
line_type VARCHAR(20), -- 'mobile', 'landline', 'voip', 'toll_free', 'premium'
carrier VARCHAR(100),
is_portable BOOLEANDEFAULTtrue,
ported_date TIMESTAMP,
created_at TIMESTAMPDEFAULTCURRENT_TIMESTAMP,
updated_at TIMESTAMPDEFAULTCURRENT_TIMESTAMP,
-- Create indexes for common queries
INDEX idx_e164 (e164_number),
INDEX idx_area_code (area_code),
INDEX idx_carrier (carrier),
INDEX idx_line_type (line_type)
);
-- Partial index for active portable numbersCREATE INDEX idx_portable_active ON phone_numbers (e164_number)
WHERE is_portable =true;
-- Composite index for lookups by area code and carrierCREATE INDEX idx_area_carrier ON phone_numbers (area_code, carrier);
Performance Optimization Tips:
Caching Strategy:
Cache validated phone numbers for 24–48 hours (TTL depends on porting frequency)
Use Redis or Memcached with keys like phone:validated:{e164_number}
Cache NPAC lookups for 1–4 hours to reduce API calls
Implement cache warming for frequently accessed numbers
Check: Verify number is not in reserved range (N11, 555-01XX)
Check: Ensure area code is exactly 671
Check: Confirm first digit of exchange (NXX) is 2–9
Solution: Use libphonenumber library for comprehensive validation
Issue: Library reports "invalid region code"
Cause: Using 'US' instead of 'GU' as region parameter
Solution: Always specify 'GU' for Guam numbers, even though country code is +1
Porting Issues
Issue: Porting request stuck in "pending" status
Check: Verify NPAC database connectivity
Check: Confirm all validation fields match carrier records exactly (case-sensitive)
Solution: Implement webhook monitoring and set timeout alerts (4 business days max)
Issue: Emergency services routing after port
Cause: ALI (Automatic Location Identification) database not updated
Solution: Verify port includes 911 database update; test emergency routing post-port
International Calling
Issue: Call to Guam fails from certain countries
Cause: Some carriers may not recognize +1 671 as distinct from U.S. mainland
Solution: Educate users to use full international format (+1 671 XXX XXXX)
Alternative: Some countries require 00 instead of + for international prefix
Issue: Unexpected international rates for U.S. mainland calls
Cause: Some non-U.S. carriers treat Guam as international despite NANP membership
Solution: Verify carrier rate tables; consider VoIP alternatives for cost-sensitive users
Frequently Asked Questions About Guam Phone Numbers
Q: Can I port a Guam number to a U.S. mainland carrier?
A: Generally no. Guam numbers must remain with Guam-based carriers due to geographic restrictions, though some VoIP providers may offer exceptions.
Q: How do I determine if a Guam number is mobile or landline?
A: NANP does not encode line type in the number. Use carrier lookup APIs (HLR/CNAM) or libphonenumber's getNumberType() function with carrier database.
Q: Are 5G features available for all Guam numbers?
A: 5G availability depends on carrier and location. Docomo Pacific has most extensive 5G coverage in urban areas; GTA and IT&E expanding. Verify with coverage maps.
Q: What happens to my number during a port?
A: Service continues with old carrier until port completes (typically 1–4 business days). Brief outage (5–15 minutes) may occur during cutover.
Q: Can I validate Guam numbers offline?
A: Basic format validation yes (using regex). Carrier verification, line type detection, and porting status require online API access.
Conclusion
You now have a comprehensive foundation for working with Guam phone numbers in your applications. This guide has covered:
NANP integration and FCC regulatory compliance requirements
Detailed number structure including NXX restrictions and reserved ranges
Production-ready validation using libphonenumber library with comprehensive test cases
Number portability implementation with error handling and webhook patterns
Carrier-specific technical details and API integration options
Database schema design and performance optimization strategies
Troubleshooting guidance for common issues
Next Steps and Resources
Implementation Checklist:
Integrate libphonenumber library for validation
Implement E.164 storage format in database
Set up NPAC database connection for porting
Configure webhook handlers for async porting updates
By following the guidelines and best practices outlined in this guide, you can ensure your application handles Guam phone numbers accurately, efficiently, and in compliance with telecommunications standards.
Frequently asked questions
The area code for Guam is 671. This code is unique to Guam and is used for all calls within the territory, whether to landlines or mobile phones. It's a crucial part of the North American Numbering Plan (NANP) structure, allowing for seamless communication with other NANP countries like the US and Canada.
Guam phone numbers in international format start with +1, followed by the area code 671, and then the 7-digit subscriber number. For example, +1 671 472 1234. This format, aligned with the E.164 standard, should be used for consistent and reliable international communication.
Guam uses the NANP due to its status as a U.S. territory. Integration into the NANP, finalized in 1997, simplified communication with North America, treating calls as domestic rather than international. This change resulted in lower costs and easier connections for both personal and business calls.
Use a regular expression (regex) like ^\+?1?\s*\(?671\)?[-.\s]?[2-9]\d{2}[-.\s]?\d{4}$ for Guam phone number validation. This pattern is flexible, accommodating variations in formatting with spaces, hyphens, and parentheses, while also handling the optional '+' sign for international numbers.
Guam landline numbers follow the NANP structure: +1 671 NXX XXXX, where N represents digits 2-9 and X can be any digit 0-9. An example would be +1 671 472 1234. This format ensures compatibility with applications designed for North American numbers.
Dial only the 7-digit subscriber number (XXX-XXXX) to make a local call within Guam from a landline. For calls from a mobile phone to either a landline or another mobile in Guam, dial 1 + 671 + the 7-digit number.
Always store phone numbers in E.164 format (+1671XXXXXXX) for consistency and interoperability in your applications. The E.164 standard ensures that phone numbers are stored in a uniform format, making it easier to process and manage them across different systems and regions.
Guam's main telecom providers include GTA, Docomo Pacific, and IT&E Guam. GTA offers a broad range of services, while Docomo Pacific focuses on urban and tourist areas, and IT&E Guam offers mobile broadband and business solutions.
Yes, number portability is available in Guam, enabling users to keep their numbers when switching carriers. The process requires integrating with number portability databases like NPAC and involves steps like customer requests, carrier verification, and database updates.
Implement real-time NPAC integration to verify porting information, automate communication between carriers, and use standardized LSR forms for requests. Consider potential porting delays of up to 4 business days in complex cases, per the provided examples.
Simple porting requests in Guam should take a maximum of one business day to complete. This requires a maximum of 4 validation fields, as outlined in the porting timelines. Complex requests can take up to 4 business days.
Docomo Pacific offers "Data To Go" roaming packages in select countries, including the US and Japan. This information is relevant for developers who need to handle roaming charges and ensure their applications function correctly for users traveling internationally.
Guam shares the country code +1 with other members of the North American Numbering Plan (NANP), including the United States and Canada. This simplifies dialing and reduces costs for calls between Guam and these countries.
Introduction
Developing an application that handles Guam phone numbers? This comprehensive guide covers everything developers need to know about the Guam phone number system, including the 671 area code, NANP integration, validation techniques, and number portability. You'll learn how to validate Guam phone numbers programmatically, understand dialing procedures, implement number porting, and follow telecommunications best practices for the U.S. territory.
Background: Guam's Telecommunications Landscape and Area Code 671
NANP Integration and Regulatory Framework
Guam's telecommunications system is deeply integrated with the North American Numbering Plan (NANP), a testament to its status as a U.S. territory. This integration, finalized in 1997, simplified communication with North America and brought Guam into a standardized numbering system. The Federal Communications Commission (FCC) maintains regulatory oversight over Guam telecommunications under Title 47 of the U.S. Code, ensuring compliance with federal telecommunications regulations.
Practical Implications for Developers:
Regulatory Authority:
Before 1997 integration, as detailed in historical accounts from the Guam Recorder, calling the U.S. mainland involved international dialing procedures and significantly higher costs, impacting communication with family and businesses.
Guam Phone Number Structure: Understanding the 671 Area Code Format
Guam phone numbers adhere to the NANP structure, making them easy to integrate into applications designed for North American numbers. Here's the breakdown:
Core Components
+1671Format Variations and Examples
While the basic structure remains consistent, you'll encounter variations based on the service type:
+1 671 NXX XXXX+1 671 NXX XXXX+1 800 XXX XXXX+1 900 XXX XXXXNote on Line Type Detection: Unlike some countries with dedicated mobile prefixes, NANP does not distinguish landline from mobile at the number level. Programmatic detection requires querying carrier databases or using specialized APIs like CNAM (Caller Name) lookup services or HLR (Home Location Register) lookups that return line type information.
NXX Exchange Code Rules and Restrictions
Key Point:
Nrepresents digits 2–9 (excluding 0 and 1), whileXcan be any digit 0–9. This distinction is crucial for accurate validation.Reserved and Restricted NXX Codes:
Valid NXX Pattern:
[2-9][0-8][0-9]or[2-9][0-9][0-9]excluding the specific reserved patterns listed above.How to Validate Guam Phone Numbers: Ensuring Data Integrity
Robust validation is essential for any application handling phone numbers. While regular expressions provide basic validation, production applications should use comprehensive libraries.
Regex Patterns for Guam Numbers
Here are regex patterns with comprehensive edge case handling:
// Basic Guam number validation (international format) const guamRegex = /^\+1\s671\s[2-9][0-9]{2}\s[0-9]{4}$/; // Extended validation with optional formatting (handles spaces, hyphens, parentheses) const extendedRegex = /^\+?1?\s*\(?671\)?[-.\s]?[2-9]\d{2}[-.\s]?\d{4}$/; // Comprehensive validation excluding reserved ranges const comprehensiveRegex = /^\+?1?\s*\(?671\)?[-.\s]?(?!555(?:01[0-9][0-9])|[2-9]11)([2-9]\d{2})[-.\s]?\d{4}$/; // Usage example with error handling function validateGuamNumber(phoneNumber) { if (!phoneNumber || typeof phoneNumber !== 'string') { return { valid: false, error: 'Invalid input type' }; } const isValid = extendedRegex.test(phoneNumber); if (!isValid) { return { valid: false, error: 'Number does not match Guam format' }; } // Check for reserved ranges const digits = phoneNumber.replace(/\D/g, ''); const exchange = digits.substr(4, 3); if (exchange.match(/^[2-9]11$/)) { return { valid: false, error: 'Reserved N11 service code' }; } return { valid: true, normalized: `+1671${digits.substr(-7)}` }; }Production-Ready Validation Libraries
For production applications, use battle-tested validation libraries instead of custom regex:
Google libphonenumber
libphonenumber-js(JavaScript/TypeScript)phonenumbers// JavaScript example with libphonenumber-js import { parsePhoneNumber, isValidPhoneNumber } from 'libphonenumber-js'; function validateGuamNumberProduction(input) { try { if (!isValidPhoneNumber(input, 'GU')) { return { valid: false, error: 'Invalid Guam phone number' }; } const phoneNumber = parsePhoneNumber(input, 'GU'); return { valid: true, e164: phoneNumber.format('E.164'), national: phoneNumber.formatNational(), international: phoneNumber.formatInternational(), type: phoneNumber.getType(), // Returns 'MOBILE', 'FIXED_LINE', etc. country: phoneNumber.country, areaCode: phoneNumber.nationalNumber.substr(0, 3) }; } catch (error) { return { valid: false, error: error.message }; } }# Python example with phonenumbers library import phonenumbers from phonenumbers import NumberParseException, carrier, geocoder def validate_guam_number_production(input_number): try: parsed = phonenumbers.parse(input_number, "GU") if not phonenumbers.is_valid_number(parsed): return {"valid": False, "error": "Invalid Guam phone number"} return { "valid": True, "e164": phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164), "national": phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.NATIONAL), "international": phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.INTERNATIONAL), "type": phonenumbers.number_type(parsed), "carrier": carrier.name_for_number(parsed, "en"), "location": geocoder.description_for_number(parsed, "en") } except NumberParseException as e: return {"valid": False, "error": str(e)}Comprehensive Test Cases
Test your validation against diverse inputs including edge cases:
const testCases = [ // Valid formats { input: '+16714721234', expected: true, description: 'E.164 format' }, { input: '+1 671 472 1234', expected: true, description: 'E.164 with spaces' }, { input: '(671) 472-1234', expected: true, description: 'National with parentheses' }, { input: '671-472-1234', expected: true, description: 'National with hyphens' }, { input: '1-671-472-1234', expected: true, description: 'NANP format with country code' }, // Invalid formats { input: '+16710721234', expected: false, description: 'Invalid NXX (starts with 0)' }, { input: '+16711721234', expected: false, description: 'Invalid NXX (starts with 1)' }, { input: '+16719111234', expected: false, description: 'Reserved 911 emergency code' }, { input: '+16714111234', expected: false, description: 'Reserved 411 directory code' }, { input: '+1671555011', expected: false, description: 'Reserved 555 test range' }, { input: '+166712341234', expected: false, description: 'Wrong area code' }, { input: '671472123', expected: false, description: 'Too short (missing digit)' }, { input: '67147212345', expected: false, description: 'Too long (extra digit)' }, { input: '+1671ABCDEFG', expected: false, description: 'Contains letters' }, { input: '', expected: false, description: 'Empty string' }, { input: null, expected: false, description: 'Null input' }, // Edge cases { input: '+1 (671) 472-1234 ext. 100', expected: false, description: 'Number with extension (requires special handling)' }, { input: ' +1 671 472 1234 ', expected: true, description: 'Extra whitespace (should trim)' }, { input: '+1.671.472.1234', expected: true, description: 'Dots as separators' } ]; // Run test suite function runValidationTests() { testCases.forEach(test => { const result = validateGuamNumber(test.input); const passed = result.valid === test.expected; console.log(`${passed ? '✓' : '✗'} ${test.description}: ${test.input}`); if (!passed) { console.log(` Expected: ${test.expected}, Got: ${result.valid}`); if (result.error) console.log(` Error: ${result.error}`); } }); }Dialing Procedures: How to Call Guam Phone Numbers
Understanding dialing procedures is crucial for applications that initiate or process calls. Here are the variations for domestic and international calls.
Domestic Calls within Guam
International Calls and Rate Information
Cost Implications:
Important for Developers: Applications that bill for call services must clearly disclose rate information and obtain user consent per FCC TCPA requirements.
Guam Number Portability: How to Port Phone Numbers Between Carriers
Number portability allows users to retain their numbers when switching carriers. This adds complexity for developers, but it's a crucial aspect of modern telecommunications. As documented by the FCC in DA 05-2714, Guam's implementation of wireless number portability has faced challenges due to infrastructure dependencies and coordination between carriers.
Porting Process and Implementation
The porting process involves several steps, including customer requests, carrier verification, and database updates. You'll need to integrate with number portability databases and handle potential delays or errors.
Key Considerations:
Porting Timeline Standards and Implementation Example
Porting timelines vary based on the complexity of the request:
// Example Number Portability Validation with comprehensive error handling function validatePortingRequest(request) { const requiredFields = ["accountNumber", "pin", "zipCode", "lastFourSSN"]; const errors = []; // Check required fields requiredFields.forEach(field => { if (!request.hasOwnProperty(field) || !request[field]) { errors.push(`Missing required field: ${field}`); } }); // Validate phone number format if (!request.phoneNumber || !validateGuamNumber(request.phoneNumber).valid) { errors.push("Invalid phone number format"); } // Validate account number (typically alphanumeric, 6-20 characters) if (request.accountNumber && !/^[A-Z0-9]{6,20}$/i.test(request.accountNumber)) { errors.push("Invalid account number format"); } // Validate PIN (typically 4-6 digits) if (request.pin && !/^\d{4,6}$/.test(request.pin)) { errors.push("Invalid PIN format (must be 4-6 digits)"); } // Validate ZIP code (5 or 9 digits) if (request.zipCode && !/^\d{5}(-\d{4})?$/.test(request.zipCode)) { errors.push("Invalid ZIP code format"); } return { valid: errors.length === 0, errors: errors }; }Common Porting Error Codes and Failure Scenarios
Understanding error codes helps implement robust retry and user notification logic:
// Webhook implementation for async porting status updates class PortingWebhookHandler { constructor(webhookUrl) { this.webhookUrl = webhookUrl; this.maxRetries = 3; this.retryDelay = 5000; // 5 seconds } async handlePortingUpdate(portRequest) { const payload = { requestId: portRequest.id, phoneNumber: portRequest.phoneNumber, status: portRequest.status, // 'pending', 'in_progress', 'completed', 'failed' timestamp: new Date().toISOString(), details: { oldCarrier: portRequest.currentProvider, newCarrier: portRequest.newProvider, focDate: portRequest.focDate, // Firm Order Commitment date errorCode: portRequest.errorCode, errorMessage: portRequest.errorMessage } }; for (let attempt = 1; attempt <= this.maxRetries; attempt++) { try { const response = await fetch(this.webhookUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Webhook-Signature': this.generateSignature(payload) }, body: JSON.stringify(payload) }); if (response.ok) { console.log(`Webhook delivered successfully on attempt ${attempt}`); return true; } console.log(`Webhook attempt ${attempt} failed with status ${response.status}`); } catch (error) { console.error(`Webhook attempt ${attempt} error:`, error.message); } if (attempt < this.maxRetries) { await this.sleep(this.retryDelay * attempt); // Exponential backoff } } // Log failed webhook for manual retry console.error('Webhook delivery failed after all retries', payload); return false; } generateSignature(payload) { // Implement HMAC-SHA256 signature for webhook security const crypto = require('crypto'); const secret = process.env.WEBHOOK_SECRET; return crypto .createHmac('sha256', secret) .update(JSON.stringify(payload)) .digest('hex'); } sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } } // Usage example const webhookHandler = new PortingWebhookHandler('https://your-app.com/webhooks/porting'); // Simulate porting status update await webhookHandler.handlePortingUpdate({ id: 'PORT-12345', phoneNumber: '+16714721234', status: 'completed', currentProvider: 'GTA', newProvider: 'DocomoPacific', focDate: '2024-10-10T12:00:00Z' });Major Guam Telecom Carriers and Service Providers
Understanding the major operators in Guam can be beneficial for your development efforts. Here's a detailed overview with technical specifications:
GTA (Guam Telephone Authority)
Docomo Pacific
IT&E Guam
Coverage Maps and Network Capabilities:
Technical Implementation: Best Practices for Guam Phone Number Integration
Following best practices ensures your application is robust, reliable, and compliant with industry standards.
E.164 Compliance: The Global Standard
The E.164 format is the international standard for phone numbers. Always store numbers in this format (
+1671XXXXXXX) for consistency and interoperability.Normalization Examples:
import re def normalize_to_e164(phone_number): """Convert various Guam number formats to E.164 standard.""" # Remove all non-digit characters digits = re.sub(r'\D', '', phone_number) # Handle different input lengths if len(digits) == 7: # Local format: add country code and area code return f'+1671{digits}' elif len(digits) == 10 and digits.startswith('671'): # National format: add country code return f'+1{digits}' elif len(digits) == 11 and digits.startswith('1671'): # NANP format: add + prefix return f'+{digits}' elif len(digits) == 11 and digits.startswith('1'): # Check if it's a Guam number if digits[1:4] == '671': return f'+{digits}' # Already in potential E.164 format or invalid return None def validate_e164(phone_number): """Validate E.164 format for Guam numbers.""" pattern = r'^\+1671[2-9]\d{6}$' return bool(re.match(pattern, phone_number)) # Example usage examples = [ '4721234', # Local format '671-472-1234', # National format with hyphens '(671) 472-1234', # National format with parentheses '1-671-472-1234', # NANP format '+1 671 472 1234' # E.164 with spaces ] for example in examples: normalized = normalize_to_e164(example) if normalized and validate_e164(normalized): print(f'✓ {example:20} → {normalized}') else: print(f'✗ {example:20} → Invalid')// JavaScript normalization example function normalizeToE164(phoneNumber) { // Remove all non-digit characters const digits = phoneNumber.replace(/\D/g, ''); // Handle different input lengths if (digits.length === 7) { // Local format: add country code and area code return `+1671${digits}`; } else if (digits.length === 10 && digits.startsWith('671')) { // National format: add country code return `+1${digits}`; } else if (digits.length === 11 && digits.startsWith('1671')) { // NANP format: add + prefix return `+${digits}`; } // Already in potential E.164 format or invalid return null; } function formatForDisplay(e164Number, locale = 'en-US') { // Format E.164 number for user-friendly display const match = e164Number.match(/^\+1(\d{3})(\d{3})(\d{4})$/); if (!match) return e164Number; const [, area, prefix, line] = match; // Return formatted based on locale preference return `(${area}) ${prefix}-${line}`; } // Example usage const input = '671-472-1234'; const e164 = normalizeToE164(input); const display = formatForDisplay(e164); console.log(`Input: ${input}`); console.log(`E.164: ${e164}`); console.log(`Display: ${display}`);Integration Best Practices
Database Schema and Performance Optimization
Recommended Database Schema:
CREATE TABLE phone_numbers ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), e164_number VARCHAR(15) NOT NULL UNIQUE, country_code VARCHAR(3) NOT NULL DEFAULT 'GU', area_code VARCHAR(3) NOT NULL, subscriber_number VARCHAR(7) NOT NULL, line_type VARCHAR(20), -- 'mobile', 'landline', 'voip', 'toll_free', 'premium' carrier VARCHAR(100), is_portable BOOLEAN DEFAULT true, ported_date TIMESTAMP, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- Create indexes for common queries INDEX idx_e164 (e164_number), INDEX idx_area_code (area_code), INDEX idx_carrier (carrier), INDEX idx_line_type (line_type) ); -- Partial index for active portable numbers CREATE INDEX idx_portable_active ON phone_numbers (e164_number) WHERE is_portable = true; -- Composite index for lookups by area code and carrier CREATE INDEX idx_area_carrier ON phone_numbers (area_code, carrier);Performance Optimization Tips:
phone:validated:{e164_number}// Redis caching example const redis = require('redis'); const client = redis.createClient(); async function getCachedValidation(phoneNumber) { const cacheKey = `phone:validated:${phoneNumber}`; const cached = await client.get(cacheKey); if (cached) { return JSON.parse(cached); } // Perform validation const result = await validateGuamNumberProduction(phoneNumber); // Cache for 24 hours await client.setex(cacheKey, 86400, JSON.stringify(result)); return result; }Retry-Afterheader// Express.js rate limiting example const rateLimit = require('express-rate-limit'); const validationLimiter = rateLimit({ windowMs: 60 * 1000, // 1 minute max: 100, // 100 requests per minute message: 'Too many validation requests, please try again later', standardHeaders: true, legacyHeaders: false, handler: (req, res) => { res.status(429).json({ error: 'Rate limit exceeded', retryAfter: req.rateLimit.resetTime }); } }); app.post('/api/validate-phone', validationLimiter, async (req, res) => { // Validation logic here });Example JSON for Porting Requests:
{ "portingRequest": { "subscriberNumber": "+16714721234", "currentProvider": "GTA", "newProvider": "DocomoPacific", "validationFields": { "accountNumber": "12345", "pin": "9999", "zipCode": "96913", "lastFourSSN": "1234" } } }Troubleshooting Common Guam Phone Number Issues
Validation Failures
Issue: Number rejected despite correct format
Issue: Library reports "invalid region code"
Porting Issues
Issue: Porting request stuck in "pending" status
Issue: Emergency services routing after port
International Calling
Issue: Call to Guam fails from certain countries
Issue: Unexpected international rates for U.S. mainland calls
Frequently Asked Questions About Guam Phone Numbers
Q: Can I port a Guam number to a U.S. mainland carrier?
A: Generally no. Guam numbers must remain with Guam-based carriers due to geographic restrictions, though some VoIP providers may offer exceptions.
Q: How do I determine if a Guam number is mobile or landline?
A: NANP does not encode line type in the number. Use carrier lookup APIs (HLR/CNAM) or libphonenumber's
getNumberType()function with carrier database.Q: Are 5G features available for all Guam numbers?
A: 5G availability depends on carrier and location. Docomo Pacific has most extensive 5G coverage in urban areas; GTA and IT&E expanding. Verify with coverage maps.
Q: What happens to my number during a port?
A: Service continues with old carrier until port completes (typically 1–4 business days). Brief outage (5–15 minutes) may occur during cutover.
Q: Can I validate Guam numbers offline?
A: Basic format validation yes (using regex). Carrier verification, line type detection, and porting status require online API access.
Conclusion
You now have a comprehensive foundation for working with Guam phone numbers in your applications. This guide has covered:
Next Steps and Resources
Implementation Checklist:
Essential Resources:
By following the guidelines and best practices outlined in this guide, you can ensure your application handles Guam phone numbers accurately, efficiently, and in compliance with telecommunications standards.