Method: validateAddress

Sprawdzanie poprawności adresu.

Żądanie HTTP

POST https://addressvalidation.googleapis.com/v1:validateAddress

Adres URL używa składni transkodowania gRPC.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
Pola
address

object (PostalAddress)

Wymagany. Adres, który jest weryfikowany. Niesformatowane adresy należy przesyłać za pomocą addressLines.

Łączna długość pól w tym wejściu nie może przekraczać 280 znaków.

Obsługiwane regiony znajdziesz tutaj.

Wartość languageCode w adresie wejściowym jest zarezerwowana do wykorzystania w przyszłości i jest ignorowana. Walidowany adres zostanie wypełniony na podstawie preferowanego języka danego adresu, jak to zostało zidentyfikowane przez system.

Interfejs API weryfikacji adresów ignoruje wartości w elementach recipients i organization. Wszystkie wartości w tych polach zostaną odrzucone i nie zostaną zwrócone. Nie ustawiaj ich.
previousResponseId

string

W przypadku pierwszego żądania weryfikacji adresu to pole musi być puste. Jeśli do pełnej weryfikacji jednego adresu potrzebne jest więcej żądań (np. jeśli zmiany wprowadzone przez użytkownika po początkowej weryfikacji wymagają ponownej weryfikacji), to w każdym kolejnym żądaniu należy wypełnić to pole wartością responseId z pierwszej odpowiedzi w sekwencji weryfikacji.
enableUspsCass

boolean

Włącza tryb zgodny z USPS CASS. Dotyczy to tylko pola google.maps.addressvalidation.v1.ValidationResult.usps_data w elementach google.maps.addressvalidation.v1.ValidationResult. Uwaga: w przypadku żądań z włączoną usługą USPS CASS dla adresów w Portoryko google.type.PostalAddress.region_code address musi być podane jako „PR”, a google.type.PostalAddress.administrative_area address jako „Portoryko” (bez względu na wielkość liter).

Zalecamy użycie komponentu address lub podanie co najmniej 2 wartości google.type.PostalAddress.address_lines, z których pierwsza zawiera numer i nazwę ulicy, a druga – miasto, województwo i kod pocztowy.
languageOptions

object (LanguageOptions)

Opcjonalnie: Wersja testowa: ta funkcja jest w wersji testowej (przed GA). Usługi i funkcje przed GA mogą mieć ograniczoną obsługę, a zmiany w takich usługach i funkcjach mogą być niezgodne z ich innymi wersjami. Oferty przed GA są objęte szczegółowymi warunkami korzystania z usługi Google Maps Platform. Więcej informacji znajdziesz w opisach etapu uruchamiania.

Umożliwia interfejsowi Address Validation API uwzględnienie dodatkowych informacji w odpowiedzi.
sessionToken

string

Opcjonalnie: Ciąg tekstowy identyfikujący sesję Autouzupełniania na potrzeby rozliczeń. Musi być bezpiecznym ciągiem znaków w formacie base64, który może zawierać maksymalnie 36 znaków ASCII. W przeciwnym razie zwracany jest błąd INVALID_ARGUMENT.

Sesja rozpoczyna się, gdy użytkownik przesyła zapytanie do funkcji autouzupełniania, a kończy, gdy wybierze miejsce i wywoła funkcję Szczegóły miejsca lub Weryfikacja adresu. Każda sesja może zawierać wiele zapytań autouzupełniania, a następnie jedno żądanie dotyczące szczegółów miejsca lub weryfikacji adresu. Dane logowania używane w przypadku każdego żądania w ramach sesji muszą należeć do tego samego projektu w Google Cloud Console. Po zakończeniu sesji token nie jest już ważny. Aplikacja musi wygenerować nowy token dla każdej sesji. Jeśli pominiesz parametr sessionToken lub użyjesz ponownie tokenu sesji, sesja zostanie obciążona opłatą tak, jakby nie podano tokenu sesji (za każde żądanie nalicza się opłata).

Uwaga: weryfikacji adresu można używać tylko w sesjach z interfejsem Autocomplete API (New), a nie Autocomplete API. Więcej informacji znajdziesz na stronie https://developers.google.com/maps/documentation/places/web-service/session-pricing.

Treść odpowiedzi

Odpowiedź na prośbę o weryfikację adresu.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
Pola
result

object (ValidationResult)

Wynik weryfikacji adresu.
responseId

string

Identyfikator UUID, który identyfikuje tę odpowiedź. Jeśli adres wymaga ponownej weryfikacji, ten identyfikator UUID musi zostać dołączony do nowej prośby.

PostalAddress

Reprezentuje adres pocztowy (np. adres do dostawy lub adres do płatności). Na podstawie adresu pocztowego usługa pocztowa może dostarczyć produkty do budynku, skrytki pocztowej lub podobnego miejsca. Nie jest ona przeznaczona do modelowania lokalizacji geograficznych (drogi, miast, gór).

W przypadku typowego użycia adres jest tworzony przez użytkownika lub za pomocą importowania istniejących danych, w zależności od typu procesu.

Wskazówki dotyczące wprowadzania i edytowania adresów: – Użyj widżetu adresu gotowego do użycia w różnych krajach, np. https://github.com/google/libaddressinput. – Użytkownicy nie powinni mieć możliwości wprowadzania danych ani edytowania pól poza krajami, w których są one używane.

Więcej informacji o korzystaniu z tego schematu znajdziesz na stronie https://support.google.com/business/answer/6397478.

Zapis JSON 
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
Pola
revision

integer

Wersja schematu PostalAddress. Każda wartość inna niż 0 spowoduje, że interfejs API zwróci błąd INVALID_ARGUMENT.
regionCode

string

Opcjonalnie: Kod regionu CLDR kraju/regionu adresu. Więcej informacji znajdziesz na stronach https://cldr.unicode.org/ i https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. Przykład: „CH” w przypadku Szwajcarii. Jeśli kod regionu nie zostanie podany, zostanie wywnioskowany na podstawie adresu. Aby uzyskać najlepszą wydajność, zalecamy podanie kodu regionu, jeśli go znasz. Niespójność lub powtarzanie się regionów może prowadzić do niskiej skuteczności. Jeśli np. addressLines już obejmuje dany region, nie podawaj w tym polu kodu tego regionu. Informacje o obsługiwanych regionach znajdziesz w sekcji Najczęstsze pytania.
languageCode

string

Kod języka w adresie wejściowym jest zarezerwowany do użycia w przyszłości i obecnie jest ignorowany. Interfejs API zwraca adres w odpowiednim języku.
postalCode

string

Opcjonalnie: Kod pocztowy w adresie. Nie we wszystkich krajach stosuje się kody pocztowe lub wymaga się ich podawania, ale tam, gdzie są używane, mogą one powodować dodatkową weryfikację innych części adresu (np. weryfikację kodu stanu lub kodu pocztowego w Stanach Zjednoczonych).
sortingCode

string

Opcjonalnie: Dodatkowy kod sortowania w danym kraju. Nie jest on używany w większości regionów. W przypadku, gdy jest używany, wartość to ciąg znaków, np. „CEDEX”, opcjonalnie z dodatkowym numerem (np. „CEDEX 7”), lub tylko liczba, która reprezentuje „kod sektora” (Jamajka), „wskaźnik obszaru dostawy” (Malawi) lub „wskaźnik urzędu pocztowego” (Wybrzeże Kości Słoniowej).
administrativeArea

string

Opcjonalnie: Najwyższy podział administracyjny, który jest używany w przypadku adresów pocztowych w kraju lub regionie. Może to być na przykład stan, prowincja, obwód lub prefektura. W Hiszpanii jest to prowincja, a nie autonomiczna społeczność (np. „Barcelona”, a nie „Katalonia”). W wielu krajach w adresach pocztowych nie podaje się obszaru administracyjnego. Na przykład w Szwajcarii nie należy wypełniać tego pola.
locality

string

Opcjonalnie: Zwykle odnosi się do części adresu zawierającej nazwę miasta. Przykłady: miasto w USA, miasto w Włoszech, miejscowość w Wielkiej Brytanii. W regionach świata, w których lokalizacja nie jest dobrze zdefiniowana lub nie pasuje do tej struktury, pozostaw pole locality puste i użyj pola addressLines.
sublocality

string

Opcjonalnie: Podjednostka adresu. Może to być na przykład dzielnica, okręg lub region.
addressLines[]

string

Wymagany. Nieuporządkowane wiersze adresu opisujące niższe poziomy adresu.

Ponieważ wartości w elementach addressLines nie zawierają informacji o typie i czasami mogą zawierać kilka wartości w pojedynczym polu (np. „Austin, TX”), ważne jest, aby kolejność wierszy była jasna. Kolejność wierszy adresu powinna odpowiadać „kolejności na kopercie” w kraju lub regionie, w którym znajduje się adres.

Minimalna dozwolona struktura adresu obejmuje wszystkie informacje umieszczone w elementach addressLines. Jeśli nie podasz wartości regionCode, region zostanie określony na podstawie wierszy adresu.

 Utworzenie adresu zawierającego tylko addressLines, a następnie geokodowanie jest zalecanym sposobem postępowania w przypadku całkowicie nieustrukturyzowanych adresów (zamiast zgadywania, które części adresu powinny być miejscowościami lub obszarami administracyjnymi).
recipients[]

string

Nie ustawiaj tego pola. Interfejs Address Validation API obecnie go nie używa. Chociaż w tej chwili interfejs API nie odrzuca żądań z tym polem ustawionym, informacje zostaną odrzucone i nie zostaną zwrócone w odpowiedzi.
organization

string

Nie ustawiaj tego pola. Interfejs Address Validation API obecnie go nie używa. Chociaż w tej chwili interfejs API nie odrzuca żądań z tym polem ustawionym, informacje zostaną odrzucone i nie zostaną zwrócone w odpowiedzi.

LanguageOptions

Wersja testowa: ta funkcja jest w wersji testowej (przed GA). Usługi i funkcje przed GA mogą mieć ograniczoną obsługę, a zmiany w takich usługach i funkcjach mogą być niezgodne z ich innymi wersjami. Oferty przed GA są objęte szczegółowymi warunkami korzystania z usługi Google Maps Platform. Więcej informacji znajdziesz w opisach etapu uruchamiania.

Umożliwia interfejsowi Address Validation API uwzględnienie dodatkowych informacji w odpowiedzi.

Zapis JSON 
{
  "returnEnglishLatinAddress": boolean
}
Pola
returnEnglishLatinAddress

boolean

Podgląd: zwraca google.maps.addressvalidation.v1.Address w języku angielskim. Więcej informacji znajdziesz w artykule google.maps.addressvalidation.v1.ValidationResult.english_latin_address.

ValidationResult

Wynik weryfikacji adresu.

Zapis JSON 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
Pola
verdict

object (Verdict)

Flagi ogólnej oceny
address

object (Address)

Informacje o samym adresie, a nie o jego geokodze.
geocode

object (Geocode)

Informacje o lokalizacji i miejscu, do których został zakodowany adres.
metadata

object (AddressMetadata)

inne informacje istotne dla skuteczności przesyłania. Nie można mieć pewności, że parametr metadata będzie w pełni wypełniony w przypadku każdego adresu wysłanego do interfejsu Address Validation API.
uspsData

object (UspsData)

dodatkowe flagi dotyczące możliwości dostarczenia przesyłki dostarczane przez USPS. Dostępne tylko w regionach US i PR.
englishLatinAddress

object (Address)

Wersja testowa: ta funkcja jest w wersji testowej (przed GA). Usługi i funkcje przed GA mogą mieć ograniczoną obsługę, a zmiany w takich usługach i funkcjach mogą być niezgodne z ich innymi wersjami. Oferty przed GA są objęte szczegółowymi warunkami korzystania z usługi Google Maps Platform. Więcej informacji znajdziesz w opisach etapu uruchamiania.

Adres przetłumaczony na język angielski.

Przetłumaczone adresy nie mogą być ponownie używane jako dane wejściowe API. Usługa udostępnia je, aby użytkownik mógł potwierdzić lub zaprzeczyć weryfikacji pierwotnie podanego adresu w jego ojczystym języku.

Jeśli część adresu nie ma tłumaczenia na język angielski, usługa zwraca tę część w innym języku, który używa alfabetu łacińskiego. Sposób wybierania języka alternatywnego znajdziesz tutaj. Jeśli część adresu nie ma tłumaczenia ani transliteracji w języku korzystającym z alfabetu łacińskiego, usługa zwraca tę część w języku lokalnym powiązanym z adresem.

Aby włączyć to wyjście, użyj parametru google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address.

Uwaga: pole google.maps.addressvalidation.v1.Address.unconfirmed_component_types w układance englishLatinAddress i pole google.maps.addressvalidation.v1.AddressComponent.confirmation_level w układance englishLatinAddress.address_components nie są wypełnione.

Wynik

Ogólne omówienie wyniku weryfikacji adresu i geokodu.

Zapis JSON 
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
Pola
inputGranularity

enum (Granularity)

Szczegółowość adresu wejścia. Jest to wynik analizy adresu wejściowego i nie zawiera żadnych sygnałów weryfikacyjnych. Informacje o weryfikacji znajdziesz w sekcji validationGranularity poniżej.

Jeśli na przykład adres wejściowy zawiera konkretny numer mieszkania, wartość inputGranularity będzie miała postać SUB_PREMISE. Jeśli nie uda nam się dopasować numeru mieszkania w bazach danych lub jeśli numer mieszkania jest nieprawidłowy, wartość validationGranularity będzie prawdopodobnie równa PREMISE lub mniejsza.
validationGranularity

enum (Granularity)

Poziom szczegółowości, na którym interfejs API może w pełni weryfikować adres. Na przykład validationGranularity PREMISE wskazuje, że można sprawdzić wszystkie elementy adresu na poziomie PREMISE lub bardziej ogólnym.

Wynik weryfikacji poszczególnych elementów adresu można znaleźć w google.maps.addressvalidation.v1.Address.address_components.
geocodeGranularity

enum (Granularity)

Informacje o szczegółowości geocode. Może to być rozumiane jako semantyczne znaczenie tego, jak ogólna lub szczegółowa jest zgeokodowana lokalizacja.

Czasami może się on różnić od podanego powyżej validationGranularity. Na przykład nasza baza danych może zawierać numer mieszkania, ale nie precyzyjne dane o jego lokalizacji w ramach dużego kompleksu mieszkaniowego. W tym przypadku validationGranularity będzie równe SUB_PREMISE, a geocodeGranularity równa się PREMISE.
addressComplete

boolean

Adres jest uważany za kompletny, jeśli nie ma nierozwiązanych tokenów ani nieoczekiwanych lub brakujących elementów adresu. Jeśli nie zostanie ustawiony, oznacza to, że jego wartość to false. Więcej informacji znajdziesz w polach missingComponentTypes, unresolvedTokens lub unexpected.
hasUnconfirmedComponents

boolean

Co najmniej jednego elementu adresu nie można zaklasyfikować ani zweryfikować. Szczegółowe informacje znajdziesz w sekcji google.maps.addressvalidation.v1.Address.address_components.
hasInferredComponents

boolean

W przypadku co najmniej jednego elementu adresu została wywnioskowana (dodana) informacja, która nie była podana w danych wejściowych. Szczegółowe informacje znajdziesz w dokumentacji google.maps.addressvalidation.v1.Address.address_components.
hasReplacedComponents

boolean

Zmieniono co najmniej 1 element adresu. Szczegółowe informacje znajdziesz w sekcji google.maps.addressvalidation.v1.Address.address_components.

Szczegółowość

Różne poziomy szczegółowości, jakie może mieć adres lub kod geograficzny. Gdy są używane do określenia dokładności adresu, wskazują, z jaką dokładnością adres wskazuje miejsce docelowe przesyłki. Na przykład adres „123 Main Street, Redwood City, CA, 94061” wskazuje na PREMISE, a „Redwood City, CA, 94061” na LOCALITY. Jeśli jednak nie uda nam się znaleźć geokodu dla „123 Main Street” w Redwood City, zwrócony geokod może mieć poziom szczegółowości LOCALITY, mimo że adres jest bardziej szczegółowy.

Wartości w polu enum
GRANULARITY_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
SUB_PREMISE Wynik poniżej poziomu budynku, np. apartament.
PREMISE Wynik na poziomie budynku.
PREMISE_PROXIMITY geokod, który w przybliżeniu określa lokalizację adresu na poziomie budynku.
BLOCK Adres lub geokod wskazują blok. Używany tylko w regionach, w których adresowanie odbywa się na poziomie bloku, np. w Japonii.
ROUTE Geokod lub adres jest dokładny do poziomu ulicy, drogi lub autostrady.
OTHER Wszystkie inne poziomy szczegółowości, które są grupowane razem, ponieważ nie można ich dostarczyć.

Adres

Szczegóły adresu po przetworzeniu. Przetwarzanie wsteczne obejmuje poprawianie błędnie zapisanych części adresu, zastępowanie niewłaściwych części i uzyskiwanie brakujących części.

Zapis JSON 
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
Pola
formattedAddress

string

Adres po przetworzeniu, sformatowany jako adres jednowierszowy zgodnie z zasadami formatowania adresów obowiązującymi w regionie, w którym się znajduje.

Uwaga: format tego adresu może być inny niż format adresu w polu postalAddress. Na przykład postalAddress zawsze reprezentuje kraj jako 2-literowy regionCode, np. „US” lub „NZ”. W tym polu używa się dłuższej formy nazwy kraju, np. „USA” lub „Nowa Zelandia”.
postalAddress

object (PostalAddress)

Adres po przetworzeniu w postaci adresu pocztowego.
addressComponents[]

object (AddressComponent)

Lista nieuporządkowana. Poszczególne elementy adresu w sformatowanym i poprawionym adresie wraz z informacjami weryfikacyjnymi. Zawiera on informacje o stanie weryfikacji poszczególnych komponentów.

Elementy adresu nie są uporządkowane w określony sposób. Nie należy zakładać kolejności elementów adresu na liście.
missingComponentTypes[]

string

Typy komponentów, które powinny być obecne w prawidłowo sformatowanym adresie e-mail, ale nie zostały znalezione w danych wejściowych ani nie można ich było wywnioskować. Przykład: ['street_number', 'route'] dla danych wejściowych takich jak „Boulder, Kolorado, 80301, USA”. Listę możliwych typów znajdziesz tutaj.

Uwaga: jeśli uważasz, że brakuje komponentu, który już został przesłany, możesz zobaczyć brakujący typ komponentu. Może się tak zdarzyć, gdy adres wejściowy zawiera nazwę budynku, ale nie numer lokalu. W adresie „渋谷区渋谷３丁目　Shibuya Stream” nazwa budynku „Shibuya Stream” ma typ komponentu premise, ale brakuje numeru lokalu, więc missingComponentTypes będzie zawierać premise.
unconfirmedComponentTypes[]

string

Typy komponentów obecnych w addressComponents, których poprawności nie udało się potwierdzić. To pole jest dostępne dla wygody użytkowników. Jego zawartość jest równoważna z przeszukiwaniem addressComponents w celu znalezienia typów wszystkich komponentów, w których confirmationLevel nie jest CONFIRMED lub flaga inferred nie jest ustawiona na true. Listę możliwych typów znajdziesz tutaj.
unresolvedTokens[]

string

tokeny w danych, których nie udało się rozwiązać; Może to być dane wejściowe, które nie zostały rozpoznane jako prawidłowa część adresu. Na przykład w przypadku danych wejściowych takich jak „Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US” nierozwiązane tokeny mogą wyglądać tak: ["Parcel", "0000123123", "&", "0000456456"].

AddressComponent

Reprezentuje element adresu, np. ulicę, miasto lub województwo.

Zapis JSON 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
Pola
componentName

object (ComponentName)

Nazwa tego komponentu.
componentType

string

Typ elementu adresu. Listę dostępnych typów znajdziesz w tabeli 2: Dodatkowe typy zwracane przez usługę Miejsca.
confirmationLevel

enum (ConfirmationLevel)

Wskazuje na poziom pewności, że komponent jest prawidłowy.
inferred

boolean

Wskazuje, że element nie był częścią danych wejściowych, ale udało nam się go odgadnąć na podstawie lokalizacji adresu i uważamy, że powinien być podany w ramach pełnego adresu.
spellCorrected

boolean

Wskazuje poprawkę do nieprawidłowego zapisu nazwy komponentu. Interfejs API nie zawsze sygnalizuje zmiany jednej wersji pisowni na inną, np. gdy „centre” zmienia się na „center”. Nie zawsze też oznacza błędy w pisownię, np. gdy zmienisz „Amphitheater Pkwy” na „Amphitheatre Pkwy”.
replaced

boolean

Wskazuje, że nazwa komponentu została zastąpiona zupełnie inną nazwą, np. nieprawidłowy kod pocztowy został zastąpiony kodem właściwym dla adresu. To nie jest zmiana kosmetyczna, ponieważ komponent wejściowy został zastąpiony innym.
unexpected

boolean

Wskazuje element adresu, który nie powinien występować w adresie pocztowym w danym regionie. Zachowaliśmy go tylko dlatego, że był częścią danych wejściowych.

ComponentName

Otoczka dla nazwy komponentu.

Zapis JSON 
{
  "text": string,
  "languageCode": string
}
Pola
text

string

Tekst nazwy. Na przykład „5th Avenue” w przypadku nazwy ulicy lub „1253” w przypadku numeru domu.
languageCode

string

Kod języka BCP-47. Nie będzie ona widoczna, jeśli nazwa komponentu nie jest powiązana z językiem, np. numer domu.

ConfirmationLevel

Różne możliwe wartości poziomów potwierdzenia.

Wartości w polu enum
CONFIRMATION_LEVEL_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
CONFIRMED Udało nam się potwierdzić, że ten element istnieje i ma sens w kontekście reszty adresu.
UNCONFIRMED_BUT_PLAUSIBLE Nie udało się potwierdzić tego komponentu, ale jest prawdopodobne, że istnieje. Może to być na przykład numer domu w znanym zakresie numerów na ulicy, na której nie ma konkretnych numerów domów.
UNCONFIRMED_AND_SUSPICIOUS Ten komponent nie został potwierdzony i prawdopodobnie jest nieprawidłowy. Może to być na przykład dzielnica, która nie pasuje do reszty adresu.

Geokodowanie

Zawiera informacje o miejscu, do którego został zgeokodowany podany tekst.

Zapis JSON 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
Pola
location

object (LatLng)

Geokodowana lokalizacja danych wejściowych.

Zalecamy używanie identyfikatorów miejsc zamiast adresów, współrzędnych geograficznych czy kodów Plus Code. Korzystanie z współrzędnych podczas wyznaczania trasy lub obliczania wskazówek dojazdu zawsze powoduje przyciąganie punktu do najbliższej drogi. Droga może nie prowadzić szybko ani bezpiecznie do miejsca docelowego i być zlokalizowana z dala od punktu dostępu do obiektu. Dodatkowo, gdy lokalizacja jest odwrotnie zgeokodowana, nie ma gwarancji, że zwrócony adres będzie zgodny z pierwotnym.
plusCode

object (PlusCode)

Plus Code odpowiadający location.
bounds

object (Viewport)

Granice miejsca powiązanego z danymi geograficznymi.
featureSizeMeters

number

Wielkość zgeokodowanego miejsca w metrach. Jest to kolejny wskaźnik dokładności zgeokodowanej lokalizacji, ale w przypadku rozmiaru fizycznego, a nie znaczenia semantycznego.
placeId

string

Identyfikator miejsca, do którego ten geokodowany przez ten input adres.

Więcej informacji o identyfikatorach miejsc znajdziesz tutaj.
placeTypes[]

string

Typy miejsc, do których zmapowano dane wejściowe. Na przykład: ['locality', 'political']. Pełną listę typów znajdziesz tutaj.

LatLng

Obiekt reprezentujący parę szerokości i długości geograficznej. Jest to para liczb podwójnie po przecinku, która reprezentuje stopnie szerokości i długości geograficznej. Jeśli nie określono inaczej, obiekt musi być zgodny ze standardem WGS84. Wartości muszą mieścić się w normalizowanych zakresach.

Zapis JSON 
{
  "latitude": number,
  "longitude": number
}
Pola
latitude

number

Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90,0, +90,0].
longitude

number

Długość geograficzna w stopniach. Musi mieścić się w zakresie [-180,0, +180,0].

PlusCode

Kod Plus Code (http://plus.codes) to odniesienie do lokalizacji w 2 formatach: kod globalny określający prostokąt o wymiarach 14 × 14 m (1/8000 stopnia) lub mniejszy oraz kod złożony, który zastępuje prefiks lokalizacją odniesienia.

Zapis JSON 
{
  "globalCode": string,
  "compoundCode": string
}
Pola
globalCode

string

Globalny (pełny) kod miejsca, np. „9FWM33GV+HQ”, reprezentujący obszar o wymiarach 1/8000 x 1/8000 stopnia (~14 x 14 metrów).
compoundCode

string

złożony kod miejsca, np. „33GV+HQ, Ramberg, Norwegia”, zawierający sufiks kodu globalnego i zastępujący prefiks nazwą sformatowanego elementu odniesienia.

Widoczny obszar

Strefa widoczna współrzędnych szerokości i długości, reprezentowana przez 2 punkty low i high, leżące na przekątnej w przeciwnych kierunkach. Widok jest uważany za zamknięty obszar, czyli obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni, a granice długości geograficznej – od -180 do 180 stopni. Przykładowe etui:

  • Jeśli low = high, widoczny obszar składa się z jednego punktu.

  • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przecina linię długości geograficznej 180°).

  • Jeśli low.longitude = –180 stopni, a high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.

  • Jeśli low.longitude = 180 stopni, a high.longitude = -180 stopni, zakres długości geograficznej jest pusty.

  • Jeśli low.latitude > high.latitude, zakres szerokości geograficznej jest pusty.

Wartości low i high muszą być wypełnione, a pole reprezentowane przez to pole nie może być puste (zgodnie z definicjami podanymi powyżej). Pusty widok spowoduje błąd.

Na przykład ten widok zawiera w pełni Nowy Jork:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

Zapis JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Pola
low

object (LatLng)

Wymagany. Najniższy punkt widocznego obszaru.
high

object (LatLng)

Wymagany. Najwyższy punkt w obszarze widoku.

AddressMetadata

Metadane adresu. Nie można mieć pewności, że parametr metadata będzie w pełni wypełniony w przypadku każdego adresu wysłanego do interfejsu Address Validation API.

Zapis JSON 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
Pola
business

boolean

Wskazuje, że jest to adres firmy. Jeśli nie jest ustawiona, oznacza, że wartość jest nieznana.
poBox

boolean

Wskazuje, że adres jest adresem skrytki pocztowej. Jeśli nie jest ustawiona, oznacza, że wartość jest nieznana.
residential

boolean

Wskazuje, że jest to adres zamieszkania. Jeśli nie jest ustawiona, oznacza, że wartość jest nieznana.

UspsData

Dane USPS dla adresu. Nie można zagwarantować, że parametr uspsData będzie w pełni wypełniony w przypadku każdego adresu w Stanach Zjednoczonych lub Portoryko wysłanego do interfejsu Address Validation API. Jeśli w odpowiedzi używasz pola uspsData jako głównego, zalecamy zintegrowanie w niej pól adresu zapasowego.

Zapis JSON 
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
Pola
standardizedAddress

object (UspsAddress)

Znormalizowany adres USPS.
deliveryPointCode

string

2-cyfrowy kod punktu dostawy
deliveryPointCheckDigit

string

Cyfra kontrolna punktu dostawy. Ta liczba jest dodawana na końcu kodu kreskowego delivery_point_barcode w przypadku skanowania poczty w sposób mechaniczny. Dodanie wszystkich cyfr z delivery_point_barcode, deliveryPointCheckDigit, kodu pocztowego i ZIP+4 powinno dać liczbę podzielną przez 10.
dpvConfirmation

string

Możliwe wartości potwierdzenia DPV. Zwraca 1 znak lub nie zwraca żadnej wartości.

  • N: nie udało się potwierdzić informacji dotyczących numeru głównego ani żadnego numeru dodatkowego.
  • D: adres został potwierdzony w DPV tylko w przypadku numeru głównego, a informacje o numerze dodatkowym były niekompletne.
  • S: adres został potwierdzony w usłudze DPV tylko w przypadku numeru głównego, a informacje o numerze dodatkowym były dostępne, ale nie zostały potwierdzone.
  • Y: adres został potwierdzony przez dostawcę usług w przypadku numeru głównego i dodatkowych numerów.
  • Pusty: jeśli odpowiedź nie zawiera wartości dpvConfirmation, adres nie został przesłany do potwierdzenia przez dostawcę.
dpvFootnote

string

Uwagi dotyczące weryfikacji punktu dostawy. W jednym ciągu może być wiele przypisów.

  • AA: adres wejściowy dopasowany do pliku ZIP+4
  • A1: adres wejściowy nie został dopasowany do pliku ZIP+4
  • BB: dopasowanie do DPV (wszystkie komponenty)
  • CC: numer dodatkowy nie został dopasowany, ale nie jest wymagany
  • C1: numer dodatkowy nie pasuje, ale jest wymagany
  • N1: brak numeru dodatkowego w adresie budynku
  • M1: brak numeru głównego
  • M3: nieprawidłowy numer główny
  • P1: brak numeru pola adresu zamówienia, RR lub HC
  • P3: nieprawidłowy adres skrytki pocztowej PO, RR lub HC
  • F1: podany adres jest zgodny z adresem wojskowym
  • G1: adres podany przez użytkownika jest zgodny z adresem ogólnym
  • U1: adres podany w formularzu musi być zgodny z unikalnym kodem pocztowym
  • PB: adres wejściowy dopasowany do rekordu PBSA
  • RR: DPV potwierdził adres za pomocą informacji z PMB
  • R1: DPV potwierdził adres bez informacji PMB
  • R7: rekord R777 lub R779 operatora trasy
  • IA: zidentyfikowano adres e-mail osoby, która została powiadomiona
  • TA: numer główny dopasowany przez odrzucenie ostatniej litery alfabetu
dpvCmra

string

Wskazuje, czy adres jest CMRA (Commercial Mail Receiving Agency) – prywatną firmą odbierającą pocztę dla klientów. Zwraca pojedynczy znak.

  • Y: adres jest adresem CMRA
  • N: adres nie jest adresem CMRA
dpvVacant

string

Czy to miejsce jest wolne? Zwraca pojedynczy znak.

  • Y: adres jest pusty
  • N: adres nie jest pusty
dpvNoStat

string

Czy to adres bez statystyk czy aktywny? Adresy bez statystyk to adresy, które nie są stale zajęte lub adresy, których USPS nie obsługuje. Zwraca pojedynczy znak.

  • Y: adres nie jest aktywny
  • N: adres jest aktywny
dpvNoStatReasonCode

integer

Wskazuje typ NoStat. Zwraca kod przyczyny jako int.

  • 1: IDA (Internal Drop Address) – adresy, na które nie są wysyłane przesyłki bezpośrednio z USPS, ale są dostarczane na adresy dostawy, które je obsługują.
  • 2: CDS – adresy, które nie są jeszcze dostępne do dostarczenia. Może to być na przykład nowy podział, w którym określono już działki i numery główne, ale nie ma jeszcze struktury dla zamieszkania.
  • 3: kolizja – adresy, które nie są faktycznie potwierdzone przez DPV.
  • 4: CMZ (uczelnie, wojsko i inne typy) – kody pocztowe i 4 rekordy USPS uwzględnione w danych.
  • 5: Regular – wskazuje adresy, na które nie dotarła przesyłka. Adresy te nie są liczone jako możliwe dostawy.
  • 6: wymagane informacje dodatkowe – adres wymaga dodatkowych informacji.
dpvDrop

string

Flaga wskazuje, że wiadomość została dostarczona do jednego urządzenia na stronie. Zwraca pojedynczy znak.

  • Y: poczta jest dostarczana do jednego adresata na stronie.
  • N: poczta nie jest dostarczana do jednego miejsca odbioru w witrynie.
dpvThrowback

string

Wskazuje, że poczta nie jest dostarczana na adres ulicy. Zwraca pojedynczy znak.

  • Y: poczta nie jest dostarczana na adres ulicy.
  • N: przesyłka jest dostarczana na adres do korespondencji.
dpvNonDeliveryDays

string

Flaga wskazuje, że dostawa poczty nie jest realizowana codziennie. Zwraca pojedynczy znak.

  • Y: dostawa poczty nie odbywa się codziennie.
  • N: brak informacji o tym, że dostawa poczty nie odbywa się codziennie.
dpvNonDeliveryDaysValues

integer

Całkowita liczba dni bez dostawy. Można go przeszukiwać za pomocą flag bitowych: 0x40 – niedziela jest dniem bez dostawy 0x20 – poniedziałek jest dniem bez dostawy 0x10 – wtorek jest dniem bez dostawy 0x08 – środa jest dniem bez dostawy 0x04 – czwartek jest dniem bez dostawy 0x02 – piątek jest dniem bez dostawy 0x01 – sobota jest dniem bez dostawy
dpvNoSecureLocation

string

Flaga wskazuje, że drzwi są dostępne, ale ze względów bezpieczeństwa nie można zostawić paczki. Zwraca pojedynczy znak.

  • Y: Ze względów bezpieczeństwa paczka nie zostanie pozostawiona.
  • N: brak informacji o tym, że paczka nie zostanie pozostawiona ze względów bezpieczeństwa.
dpvPbsa

string

Wskazuje, że adres został dopasowany do rekordu PBSA. Zwraca pojedynczy znak.

  • Y: adres został dopasowany do rekordu PBSA.
  • N: adres nie został dopasowany do rekordu PBSA.
dpvDoorNotAccessible

string

Flaga wskazuje adresy, w przypadku których USPS nie może zapukać do drzwi, aby dostarczyć przesyłkę. Zwraca pojedynczy znak.

  • Y: drzwi są niedostępne.
  • N: brak informacji o tym, że drzwi są niedostępne.
dpvEnhancedDeliveryCode

string

Wskazuje, że w przypadku adresu jest ważny więcej niż 1 kod zwrotu DPV. Zwraca pojedynczy znak.

  • Y: adres został potwierdzony przez dostawcę usług w przypadku numeru głównego i dodatkowych numerów.
  • N: nie udało się potwierdzić informacji dotyczących numeru głównego ani żadnego numeru dodatkowego.
  • S: adres został potwierdzony w ramach weryfikacji danych osobowych tylko w przypadku numeru głównego, a informacje o numerze dodatkowym były obecne, ale nie zostały potwierdzone. Albo też z numeru głównego usunięto jedną literę, aby dopasować dane osobowe i wymagać informacji dodatkowych.
  • D: adres został potwierdzony w DPV tylko w przypadku numeru głównego, a informacje o numerze dodatkowym były niekompletne.
  • R: adres został potwierdzony, ale został przypisany do fikcyjnej trasy R777 i R779, a usługa USPS nie została wybrana.
carrierRoute

string

Kod trasy przewoźnika. Czterozyłowy kod składający się z jednoliterowego prefiksu i trzycyfrowego wskaźnika trasy.

Prefiksy:

  • C: trasa przewoźnika (lub trasa miejska)
  • R: trasa wiejska
  • H: umowa na autostradę
  • B: sekcja skrzynki pocztowej
  • G: ogólna jednostka dostawy
carrierRouteIndicator

string

Wskaźnik sortowania stawki trasy przewoźnika.
ewsNoMatch

boolean

Adres dostawy można dopasować, ale plik EWS wskazuje, że dokładne dopasowanie będzie dostępne wkrótce.
postOfficeCity

string

Główny urząd pocztowy w mieście.
postOfficeState

string

Stan głównego urzędu pocztowego.
abbreviatedCity

string

Skrót nazwy miasta.
fipsCountyCode

string

Kod FIPS hrabstwa.
county

string

Nazwa powiatu.
elotNumber

string

Numer rozszerzonej linii podróży (eLOT).
elotFlag

string

eLOT Flaga rosnąca/malejąca (A/D).
poBoxOnlyPostalCode

boolean

Kod pocztowy tylko dla skrzynki pocztowej.
pmbDesignator

string

PMB (Private Mail Box) – identyfikator jednostki.
pmbNumber

string

Numer PMB (Private Mail Box);
addressRecordType

string

Typ rekordu adresu pasującego do adresu wejściowego.

  • F: FIRM. Jest to dopasowanie do rekordu firmy, czyli dopasowanie na najniższym poziomie dostępne dla adresu.
  • G: OGÓLNA DOSTAWA. Jest to dopasowanie do rekordu ogólnego.
  • H: BUDYNKI / MIESZKANIA. Dopasowanie do rekordu budynku lub mieszkania.
  • P: Skrzynka pocztowa. To jest skrzynka pocztowa.
  • R: RURAL ROUTE lub HIGHWAY CONTRACT: to dopasowanie do rekordu dotyczącego umowy dotyczącej drogi wiejskiej lub autostrady. Oba rekordy mogą mieć powiązane zakresy numerów skrzynek.
  • S: RECORD STREET: dopasowanie do rekordu ulicy zawierającego prawidłowy zakres numerów głównych.
defaultAddress

boolean

Wskaźnik, że znaleziono adres domyślny, ale istnieją bardziej szczegółowe adresy.
errorMessage

string

Komunikat o błędzie podczas pobierania danych USPS To pole jest wypełniane, gdy przetwarzanie przez USPS jest zawieszone z powodu wykrycia sztucznie utworzonych adresów.

Gdy wystąpi ten błąd, pola danych USPS mogą nie zostać wypełnione.
cassProcessed

boolean

Wskaźnik, że żądanie zostało przetworzone przez CASS.

UspsAddress

Adres w Stanach Zjednoczonych według USPS.

Zapis JSON 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
Pola
firstAddressLine

string

Pierwszy wiersz adresu.
firm

string

Nazwa firmy.
secondAddressLine

string

Drugi wiersz adresu.
urbanization

string

Nazwa portorykańskiej urbanizacji.
cityStateZipAddressLine

string

Miasto + stan + kod pocztowy.
city

string

Nazwa miasta.
state

string

2-literowy kod stanu.
zipCode

string

Kod pocztowy, np. 10009.
zipCodeExtension

string

4-cyfrowy kod pocztowy, np. 5023.