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 20syntax = "proto2"; 21 22option java_package = "com.google.i18n.phonenumbers"; 23option optimize_for = LITE_RUNTIME; 24 25package i18n.phonenumbers; 26 27message PhoneNumber { 28 // The country calling code for this number, as defined by the International 29 // Telecommunication Union (ITU). For example, this would be 1 for NANPA 30 // countries, and 33 for France. 31 required int32 country_code = 1; 32 33 // The National (significant) Number, as defined in International 34 // Telecommunication Union (ITU) Recommendation E.164, without any leading 35 // zero. The leading-zero is stored separately if required, since this is an 36 // uint64 and hence cannot store such information. Do not use this field 37 // directly: if you want the national significant number, call the 38 // getNationalSignificantNumber method of PhoneNumberUtil. 39 // 40 // For countries which have the concept of an "area code" or "national 41 // destination code", this is included in the National (significant) Number. 42 // Although the ITU says the maximum length should be 15, we have found longer 43 // numbers in some countries e.g. Germany. 44 // Note that the National (significant) Number does not contain the National 45 // (trunk) prefix. Obviously, as a uint64, it will never contain any 46 // formatting (hyphens, spaces, parentheses), nor any alphanumeric spellings. 47 required uint64 national_number = 2; 48 49 // Extension is not standardized in ITU recommendations, except for being 50 // defined as a series of numbers with a maximum length of 40 digits. It is 51 // defined as a string here to accommodate for the possible use of a leading 52 // zero in the extension (organizations have complete freedom to do so, as 53 // there is no standard defined). Other than digits, some other dialling 54 // characters such as "," (indicating a wait) may be stored here. 55 optional string extension = 3; 56 57 // In some countries, the national (significant) number starts with one or 58 // more "0"s without this being a national prefix or trunk code of some kind. 59 // For example, the leading zero in the national (significant) number of an 60 // Italian phone number indicates the number is a fixed-line number. There 61 // have been plans to migrate fixed-line numbers to start with the digit two 62 // since December 2000, but it has not happened yet. See 63 // http://en.wikipedia.org/wiki/%2B39 for more details. 64 // 65 // These fields can be safely ignored (there is no need to set them) for most 66 // countries. Some limited number of countries behave like Italy - for these 67 // cases, if the leading zero(s) of a number would be retained even when 68 // dialling internationally, set this flag to true, and also set the number of 69 // leading zeros. 70 // 71 // Clients who use the parsing functionality of the i18n phone 72 // number libraries will have these fields set if necessary automatically. 73 optional bool italian_leading_zero = 4; 74 optional int32 number_of_leading_zeros = 8 [ default = 1 ]; 75 76 // The next few fields are non-essential fields for a phone number. They 77 // retain extra information about the form the phone number was in when it was 78 // provided to us to parse. They can be safely ignored by most clients. To 79 // populate them, call parseAndKeepRawInput on PhoneNumberUtil. 80 81 // This field is used to store the raw input string containing phone numbers 82 // before it was canonicalized by the library. For example, it could be used 83 // to store alphanumerical numbers such as "1-800-GOOG-411". 84 optional string raw_input = 5; 85 86 // The source from which the country_code is derived. This is not set in the 87 // general parsing method, but in the method that parses and keeps raw_input. 88 // New fields could be added upon request. 89 enum CountryCodeSource { 90 // Default value returned if this is not set, because the phone number was 91 // created using parse, not parseAndKeepRawInput. hasCountryCodeSource will 92 // return false if this is the case. 93 UNSPECIFIED = 0; 94 95 // The country_code is derived based on a phone number with a leading "+", 96 // e.g. the French number "+33 1 42 68 53 00". 97 FROM_NUMBER_WITH_PLUS_SIGN = 1; 98 99 // The country_code is derived based on a phone number with a leading IDD, 100 // e.g. the French number "011 33 1 42 68 53 00", as it is dialled from US. 101 FROM_NUMBER_WITH_IDD = 5; 102 103 // The country_code is derived based on a phone number without a leading 104 // "+", e.g. the French number "33 1 42 68 53 00" when defaultCountry is 105 // supplied as France. 106 FROM_NUMBER_WITHOUT_PLUS_SIGN = 10; 107 108 // The country_code is derived NOT based on the phone number itself, but 109 // from the defaultCountry parameter provided in the parsing function by the 110 // clients. This happens mostly for numbers written in the national format 111 // (without country code). For example, this would be set when parsing the 112 // French number "01 42 68 53 00", when defaultCountry is supplied as 113 // France. 114 FROM_DEFAULT_COUNTRY = 20; 115 } 116 117 // The source from which the country_code is derived. 118 optional CountryCodeSource country_code_source = 6; 119 120 // The carrier selection code that is preferred when calling this phone number 121 // domestically. This also includes codes that need to be dialed in some 122 // countries when calling from landlines to mobiles or vice versa. For 123 // example, in Columbia, a "3" needs to be dialed before the phone number 124 // itself when calling from a mobile phone to a domestic landline phone and 125 // vice versa. 126 // 127 // Note this is the "preferred" code, which means other codes may work as 128 // well. 129 optional string preferred_domestic_carrier_code = 7; 130} 131 132// Examples: 133// 134// Google MTV, +1 650-253-0000, (650) 253-0000 135// country_code: 1 136// national_number: 6502530000 137// 138// Google Paris, +33 (0)1 42 68 53 00, 01 42 68 53 00 139// country_code: 33 140// national_number: 142685300 141// 142// Google Beijing, +86-10-62503000, (010) 62503000 143// country_code: 86 144// national_number: 1062503000 145// 146// Google Italy, +39 02-36618 300, 02-36618 300 147// country_code: 39 148// national_number: 236618300 149// italian_leading_zero: true 150