1 /* 2 * Copyright (C) 2009 The Libphonenumber Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 // Definition of protocol buffer for representing international telephone numbers. 18 // @author Shaopeng Jia 19 20 syntax = "proto2"; 21 22 option java_package = "com.google.i18n.phonenumbers"; 23 option optimize_for = LITE_RUNTIME; 24 25 package i18n.phonenumbers; 26 27 message PhoneNumber { 28 // The country calling code for this number, as defined by the International Telecommunication Union 29 // (ITU). Fox example, this would be 1 for NANPA countries, and 33 for France. 30 required int32 country_code = 1; 31 32 // National (significant) Number is defined in International Telecommunication Union Recommendation 33 // E.164. It is a language/country-neutral representation of a phone number at a country level. For 34 // countries which have the concept of Area Code, the National (significant) Number contains the 35 // area code. It contains a maximum number of digits which equal to 15 - n, where n is the number of 36 // digits of the country code. Take note that National (significant) Number does not contain 37 // National(trunk) prefix. Obviously, as a uint64, it will never contain any formatting (hypens, 38 // spaces, parentheses), nor any alphanumeric spellings. 39 required uint64 national_number = 2; 40 41 // Extension is not standardized in ITU recommendations, except for being defined as a series of 42 // numbers with a maximum length of 40 digits. It is defined as a string here to accommodate for the 43 // possible use of a leading zero in the extension (organizations have complete freedom to do so, 44 // as there is no standard defined). However, only ASCII digits should be stored here. 45 optional string extension = 3; 46 47 // In some countries, the national (significant) number starts with a "0" without this being a 48 // national prefix or trunk code of some kind. For example, the leading zero in the national 49 // (significant) number of an Italian phone number indicates the number is a fixed-line number. 50 // There have been plans to migrate fixed-line numbers to start with the digit two since December 51 // 2000, but it has not happened yet. See http://en.wikipedia.org/wiki/%2B39 for more details. 52 // 53 // This field can be safely ignored (there is no need to set it) for most countries. Some limited 54 // amount of countries behave like Italy - for these cases, if the leading zero of a number would be 55 // retained even when dialling internationally, set this flag to true. 56 // 57 // Clients who use the parsing functionality of the i18n phone number libraries 58 // will have this field set if necessary automatically. 59 optional bool italian_leading_zero = 4; 60 61 // The next few fields are non-essential fields for a phone number. They retain extra information 62 // about the form the phone number was in when it was provided to us to parse. They can be safely 63 // ignored by most clients. 64 65 // This field is used to store the raw input string containing phone numbers before it was 66 // canonicalized by the library. For example, it could be used to store alphanumerical numbers 67 // such as "1-800-GOOG-411". 68 optional string raw_input = 5; 69 70 // The source from which the country_code is derived. This is not set in the general parsing method, 71 // but in the method that parses and keeps raw_input. New fields could be added upon request. 72 enum CountryCodeSource { 73 // The country_code is derived based on a phone number with a leading "+", e.g. the French 74 // number "+33 (0)1 42 68 53 00". 75 FROM_NUMBER_WITH_PLUS_SIGN = 1; 76 77 // The country_code is derived based on a phone number with a leading IDD, e.g. the French 78 // number "011 33 (0)1 42 68 53 00", as it is dialled from US. 79 FROM_NUMBER_WITH_IDD = 5; 80 81 // The country_code is derived based on a phone number without a leading "+", e.g. the French 82 // number "33 (0)1 42 68 53 00" when defaultCountry is supplied as France. 83 FROM_NUMBER_WITHOUT_PLUS_SIGN = 10; 84 85 // The country_code is derived NOT based on the phone number itself, but from the defaultCountry 86 // parameter provided in the parsing function by the clients. This happens mostly for numbers 87 // written in the national format (without country code). For example, this would be set when 88 // parsing the French number "(0)1 42 68 53 00", when defaultCountry is supplied as France. 89 FROM_DEFAULT_COUNTRY = 20; 90 } 91 92 // The source from which the country_code is derived. 93 optional CountryCodeSource country_code_source = 6; 94 95 // The carrier selection code that is preferred when calling this phone number domestically. This 96 // also includes codes that need to be dialed in some countries when calling from landlines to 97 // mobiles or vice versa. For example, in Columbia, a "3" needs to be dialed before the phone number 98 // itself when calling from a mobile phone to a domestic landline phone and vice versa. 99 // 100 // Note this is the "preferred" code, which means other codes may work as well. 101 optional string preferred_domestic_carrier_code = 7; 102 } 103 104 // Examples 105 // 106 // Google MTV, +1 650-253-0000, (650) 253-0000 107 // country_code: 1 108 // national_number: 6502530000 109 // 110 // Google Paris, +33 (0)1 42 68 53 00, 01 42 68 53 00 111 // country_code: 33 112 // national_number: 142685300 113 // 114 // Google Beijing, +86-10-62503000, (010) 62503000 115 // country_code: 86 116 // national_number: 1062503000 117 // 118 // Google Italy, +39 02-36618 300, 02-36618 300 119 // country_code: 39 120 // national_number: 236618300 121 // italian_leading_zero: true 122
