1// Copyright 2020 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.type; 18 19option cc_enable_arenas = true; 20option go_package = "type"; 21option java_multiple_files = true; 22option java_outer_classname = "PostalAddressProto"; 23option java_package = "com.google.type"; 24option objc_class_prefix = "GTP"; 25 26// Represents a postal address, e.g. for postal delivery or payments addresses. 27// Given a postal address, a postal service can deliver items to a premise, P.O. 28// Box or similar. 29// It is not intended to model geographical locations (roads, towns, 30// mountains). 31// 32// In typical usage an address would be created via user input or from importing 33// existing data, depending on the type of process. 34// 35// Advice on address input / editing: 36// - Use an i18n-ready address widget such as 37// https://github.com/google/libaddressinput) 38// - Users should not be presented with UI elements for input or editing of 39// fields outside countries where that field is used. 40// 41// For more guidance on how to use this schema, please see: 42// https://support.google.com/business/answer/6397478 43message PostalAddress { 44 // The schema revision of the `PostalAddress`. This must be set to 0, which is 45 // the latest revision. 46 // 47 // All new revisions **must** be backward compatible with old revisions. 48 int32 revision = 1; 49 50 // Required. CLDR region code of the country/region of the address. This 51 // is never inferred and it is up to the user to ensure the value is 52 // correct. See http://cldr.unicode.org/ and 53 // http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html 54 // for details. Example: "CH" for Switzerland. 55 string region_code = 2; 56 57 // Optional. BCP-47 language code of the contents of this address (if 58 // known). This is often the UI language of the input form or is expected 59 // to match one of the languages used in the address' country/region, or their 60 // transliterated equivalents. 61 // This can affect formatting in certain countries, but is not critical 62 // to the correctness of the data and will never affect any validation or 63 // other non-formatting related operations. 64 // 65 // If this value is not known, it should be omitted (rather than specifying a 66 // possibly incorrect default). 67 // 68 // Examples: "zh-Hant", "ja", "ja-Latn", "en". 69 string language_code = 3; 70 71 // Optional. Postal code of the address. Not all countries use or require 72 // postal codes to be present, but where they are used, they may trigger 73 // additional validation with other parts of the address (e.g. state/zip 74 // validation in the U.S.A.). 75 string postal_code = 4; 76 77 // Optional. Additional, country-specific, sorting code. This is not used 78 // in most regions. Where it is used, the value is either a string like 79 // "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number 80 // alone, representing the "sector code" (Jamaica), "delivery area indicator" 81 // (Malawi) or "post office indicator" (e.g. Côte d'Ivoire). 82 string sorting_code = 5; 83 84 // Optional. Highest administrative subdivision which is used for postal 85 // addresses of a country or region. 86 // For example, this can be a state, a province, an oblast, or a prefecture. 87 // Specifically, for Spain this is the province and not the autonomous 88 // community (e.g. "Barcelona" and not "Catalonia"). 89 // Many countries don't use an administrative area in postal addresses. E.g. 90 // in Switzerland this should be left unpopulated. 91 string administrative_area = 6; 92 93 // Optional. Generally refers to the city/town portion of the address. 94 // Examples: US city, IT comune, UK post town. 95 // In regions of the world where localities are not well defined or do not fit 96 // into this structure well, leave locality empty and use address_lines. 97 string locality = 7; 98 99 // Optional. Sublocality of the address. 100 // For example, this can be neighborhoods, boroughs, districts. 101 string sublocality = 8; 102 103 // Unstructured address lines describing the lower levels of an address. 104 // 105 // Because values in address_lines do not have type information and may 106 // sometimes contain multiple values in a single field (e.g. 107 // "Austin, TX"), it is important that the line order is clear. The order of 108 // address lines should be "envelope order" for the country/region of the 109 // address. In places where this can vary (e.g. Japan), address_language is 110 // used to make it explicit (e.g. "ja" for large-to-small ordering and 111 // "ja-Latn" or "en" for small-to-large). This way, the most specific line of 112 // an address can be selected based on the language. 113 // 114 // The minimum permitted structural representation of an address consists 115 // of a region_code with all remaining information placed in the 116 // address_lines. It would be possible to format such an address very 117 // approximately without geocoding, but no semantic reasoning could be 118 // made about any of the address components until it was at least 119 // partially resolved. 120 // 121 // Creating an address only containing a region_code and address_lines, and 122 // then geocoding is the recommended way to handle completely unstructured 123 // addresses (as opposed to guessing which parts of the address should be 124 // localities or administrative areas). 125 repeated string address_lines = 9; 126 127 // Optional. The recipient at the address. 128 // This field may, under certain circumstances, contain multiline information. 129 // For example, it might contain "care of" information. 130 repeated string recipients = 10; 131 132 // Optional. The name of the organization at the address. 133 string organization = 11; 134} 135