mobile-carriers
v1.1.3
Published
A list of telcos with their prefixes and their support for mobile money services
Downloads
410
Readme
Mobile Carrier Finder Package
This package provides utilities to find mobile network carriers based on phone numbers and to retrieve information about mobile networks across various countries.
Installation
First, you need to install the package in your Node.js project:
npm install mobile-carriers
Usage
Importing the Package
Before you can use the functions, import them into your project file:
const {
findNetworkByPhoneNumber,
getNetworkPrefixes,
getMobileMoneyNetworks,
getCountriesWithNetwork,
phoneNumberLookup,
validatePhoneNumber,
getTelcoByPhoneNumber,
getTelcosByCountry
} = require('mobile-carriers');
Functions
1. Find Network by Phone Number
This function takes a phone number and optionally a country code. It returns the network the phone number belongs to.
Example:
console.log(findNetworkByPhoneNumber('08031234567', '+234'));
// Output: 'MTN'
If you do not know the country code, the function tries to infer it from the phone number:
Example:
console.log(findNetworkByPhoneNumber('+2348031234567'));
// Output: 'MTN'
2. Get Network Prefixes
This function takes a network name, capitalizes it, and returns all prefixes associated with that network in all countries.
Example:
console.log(getNetworkPrefixes('MTN'));
// Output: ['0803', '0806', '0703', ...]
3. Get Mobile Money Networks
Retrieve a list of all networks offering mobile money services in a specified country.
Example:
console.log(getMobileMoneyNetworks('Ghana'));
// Output: ['MTN', 'Vodafone', 'AirtelTigo']
4. Get Countries with Network
Provides a list of countries where a specific network is operational.
Example:
console.log(getCountriesWithNetwork('MTN'));
// Output: ['Nigeria', 'Ghana', 'Ivory Coast', ...]
5. Phone Number Lookup
This function takes a phone number and returns detailed information about it, including the country code, local phone number, network, and mobile money capability.
Example:
console.log(phoneNumberLookup('+2330549115756'));
// Output: {
// "phoneNumber": "+2330549115756",
// "countryCode": "+233",
// "localPhoneNumber": "0549115756",
// "network": "MTN",
// "mobileMoney": true,
// "isValid": true
// }
6. Validate Phone Number
This function validates a phone number using the country's regex pattern.
Example:
console.log(validatePhoneNumber('+2330549115756'));
// Output: true
7. Get Telco by Phone Number
This function retrieves the telco information based on the phone number.
Example:
console.log(getTelcoByPhoneNumber('+2330549115756'));
// Output: 'MTN'
8. Get Telcos in a Country
This function retrieves all telcos in a specified country using the country code.
Example:
console.log(getTelcosByCountry('+233'));
// Output: {
// countryCode: '+233',
// isoCode: 'GH',
// networks: { ... }
// }
How to Contribute to the Mobile-carriers Repository
This repository serves as a comprehensive database of mobile carrier prefixes from various countries. We welcome contributions, especially those that help expand our coverage or correct existing information. Here's how you can help:
Contribution Guidelines
1. Formatting Your Contribution
When adding new carriers or prefixes, please adhere to the following JSON structure for consistency and ease of integration:
{
"Country Name": {
"countryCode": "+<country_code>",
"isoCode": "<iso_code>",
"regex": "<regex_pattern>",
"networks": {
"Carrier Name": {
"prefixes": ["Prefix1", "Prefix2", ...],
"mobileMoney": true
},
"Another Carrier": {
"prefixes": ["Prefix1"],
"mobileMoney": false
}
}
}
}
Example:
{
"Ghana": {
"countryCode": "+233",
"isoCode": "GH",
"regex": "^(?:\+233)(0?)(20|23|24|26|27|28|50|54|55|56|57|58|59)\d{7}$",
"networks": {
"MTN": {
"prefixes": ["024", "054", "055", "059"],
"mobileMoney": true
},
"Vodafone": {
"prefixes": ["020"],
"mobileMoney": true
},
"AirtelTigo": {
"prefixes": ["026", "027", "056", "057"],
"mobileMoney": true
}
}
}
}
Ensure each mobile network prefix you add is validated and accurate. For instance, if the international dialing code for Ghana is +233, then +233549115753 or +2330549115753 should be a valid phone number.
2. Submitting Your Contribution
After adding the country and network prefixes:
- Create a Pull Request (PR): Include your changes in a PR for review.
- Validation: Ensure you validate each number prefix added.
- JSON Linting: Use a JSON linter to check the syntax of your updates.
- References: Provide sources or references you used to verify the prefixes. This could be official carrier websites or telecommunications regulatory publications.
Support
For any issues or further questions, please open an issue on the GitHub repository.