Class PhoneGeoLocator
Create an instance that can geographically locate a phone number.
The location of the number is calculated according to the following rules:
- If the areaCode property is undefined or empty, or if the number specifies a country code for which we do not have information, then the area property may be missing from the returned object. In this case, only the country object will be returned.
- If there is no area code, but there is a mobile prefix, service code, or emergency code, then a fixed string indicating the type of number will be returned.
- The country object is filled out according to the countryCode property of the phone number.
- If the phone number does not have an explicit country code, the MCC will be used if it is available. The country code can be gleaned directly from the MCC. If the MCC of the carrier to which the phone is currently connected is available, it should be passed in so that local phone numbers will look correct.
- If the country's dialling plan mandates a fixed length for phone numbers, and a particular number exceeds that length, then the area code will not be given on the assumption that the number has problems in the first place and we cannot guess correctly.
If the number passed in is invalid, no geolocation will be performed. If the location information about the country where the phone number is located is not available, then the area information will be missing and only the country will be available.
The options parameter can contain any one of the following properties:
- locale The locale parameter is used to load translations of the names of regions and areas if available. For example, if the locale property is given as "en-US" (English for USA), but the phone number being geolocated is in Germany, then this class would return the the names of the country (Germany) and region inside of Germany in English instead of German. That is, a phone number in Munich and return the country "Germany" and the area code "Munich" instead of "Deutschland" and "München". The default display locale is the current ilib locale. If translations are not available, the region and area names are given in English, which should always be available.
- mcc The mcc of the current mobile carrier, if known.
- onLoad - a callback function to call when the data for the locale is fully loaded. When the onLoad option is given, this object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
- loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.
Defined in: PhoneGeoLocator.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
PhoneGeoLocator(options)
|
| Method Attributes | Method Name and Description |
|---|---|
|
country(number)
Returns a string that describes the ISO-3166-2 country code of the given phone
number.
|
|
|
locate(number, options)
Returns a the location of the given phone number, if known.
|
Class Detail
PhoneGeoLocator(options)
- Parameters:
- {Object} options
- parameters controlling the geolocation of the phone number.
Method Detail
{string}
country(number)
Returns a string that describes the ISO-3166-2 country code of the given phone
number.
If the phone number is a local phone number and does not contain any country information, this routine will return the region for the current formatter instance.
- Parameters:
- {PhoneNumber} number
- An PhoneNumber instance
- Returns:
- {string}
{Object}
locate(number, options)
Returns a the location of the given phone number, if known.
The returned object has 2 properties, each of which has an sn (short name)
and an ln (long name) string. Additionally, the country code, if given,
includes the 2 letter ISO code for the recognized country.
{
"country": {
"sn": "North America",
"ln": "North America and the Caribbean Islands",
"code": "us"
},
"area": {
"sn": "California",
"ln": "Central California: San Jose, Los Gatos, Milpitas, Sunnyvale, Cupertino, Gilroy"
}
}
The location name is subject to the following rules:
If the areaCode property is undefined or empty, or if the number specifies a
country code for which we do not have information, then the area property may be
missing from the returned object. In this case, only the country object will be returned.
If there is no area code, but there is a mobile prefix, service code, or emergency
code, then a fixed string indicating the type of number will be returned.
The country object is filled out according to the countryCode property of the phone
number.
If the phone number does not have an explicit country code, the MCC will be used if
it is available. The country code can be gleaned directly from the MCC. If the MCC
of the carrier to which the phone is currently connected is available, it should be
passed in so that local phone numbers will look correct.
If the country's dialling plan mandates a fixed length for phone numbers, and a
particular number exceeds that length, then the area code will not be given on the
assumption that the number has problems in the first place and we cannot guess
correctly.
The returned area property varies in specificity according
to the locale. In North America, the area is no finer than large parts of states
or provinces. In Germany and the UK, the area can be as fine as small towns.
The strings returned from this function are already localized to the
given locale, and thus are ready for display to the user.
If the number passed in is invalid, an empty object is returned. If the location
information about the country where the phone number is located is not available,
then the area information will be missing and only the country will be returned.
The options parameter can contain any one of the following properties:
- locale The locale parameter is used to load translations of the names of regions and areas if available. For example, if the locale property is given as "en-US" (English for USA), but the phone number being geolocated is in Germany, then this class would return the the names of the country (Germany) and region inside of Germany in English instead of German. That is, a phone number in Munich and return the country "Germany" and the area code "Munich" instead of "Deutschland" and "München". The default display locale is the current ilib locale. If translations are not available, the region and area names are given in English, which should always be available.
- mcc The mcc of the current mobile carrier, if known.
- onLoad - a callback function to call when the data for the locale is fully loaded. When the onLoad option is given, this object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
- loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.
- Parameters:
- {PhoneNumber} number
- phone number to locate
- {Object} options
- options governing the way this ares is loaded
- Returns:
- {Object} an object that describes the country and the area in that country corresponding to this phone number. Each of the country and area contain a short name (sn) and long name (ln) that describes the location.