Informacje o współrzędnych geograficznych uzyskujemy za pomocą aplikacji Google Maps Geocoding API przekazując zapytania, a właściwie żądania HTTP, w następującej postaci: https://maps.googleapis.com/maps/api/geocode/output?parameters

output:

może przyjmować jedną z wartości:

json:

dane zwracane będą w tekstowym formacie JSON (JavaScript Object Notation).

xml:

dane zwracane będą w tekstowym formacie XML (Extensible Markup Language).

parameters:

lista parametrów rozdzielonych znakiem ampersand (&). Niektóre parametry są wymagane, ale większość parametrów jest opcjonalna (usługa Google Directions API stosuje wtedy wartość domyślną, lub pomija niewymagany parametr). Lista parametrów, które mogą być przekazane w adresie URL, oraz ich dopuszczalne wartości wymienione są poniżej:

address:

(wymagany) - adres miejsca którego współrzędne geograficzne chcemy pobrać. Parametr adress należy przekazać „w formacie używanym przez krajowe służby pocztowej danego kraju”.
https://maps.googleapis.com/maps/api/geocode/xml?address=Ogród Saski,lubelskie,Lublin,PL

lub
components:

(wymagany, jeżeli parametr address jest nieużywany) - Filtr służący do ograniczenia wyszukiwania do określonego obszaru w którym znajduje się element dla którego, chcemy pobrać współrzędne geogeaficzne. Filtr składa się z listy par: component:value oddzielonych znakiem kreski pipe) (|) Filtr components będzie akceptowany jako opcjonalny parametr, jeśli pierwszy parametr adress jest prawidłowy.

Filtr components może zawierać poniższe elementy:

route:

długa lub krótka nazwa drogi.

locality:

miejscowości i ich mniejsze jednostki terytorialne

administrative_area:

obszary administracyjne

postal_code:

kod pocztowy

country:

pełna nazwa kraju lub jego dwuliterowe oznaczenie w/g ISO 3166-1
https://maps.googleapis.com/maps/api/geocode/xml?&components=country:PL|administrative_area:Lublin|locality:Śródmieście

bounds:

współrzędne geograficzne obszaru przekazane jako współrzędne prawego-górnego narożnika i lewego-dolnego narożnika, oddzielonych znakiem kreski pipe ()|). Parametr ten spełnia rolę pomocniczą. Nie ogranicza wyszukiwania do przekazanego obszaru.

language:

określa język w jakim mają być zwrócone wyniki.

region:

dwuliterowy kod regionu, określonego jako ccTLD (krajowa domena najwyższego poziomu).

region:

dwuliterowy kod regionu, określonego jako ccTLD (krajowa domena najwyższego poziomu).

Odpowiedzi na żądanie HTTP Geocoding API są zwracane w formacie przekazanym w argumencie output w adresie URL.

json: dane zwracane będą w tekstowym formacie JSON (JavaScript Object Notation).

Zwracany dokument JSON składa się z dwóch elementów:

status:

zawierający metadane dotyczące wyniku żądania, patrz Kody wyniku poniżej

results:

tablica zawierająca dane dotyczące przekazanego adresu, przy braku wyników tablica jest pusta

xml: dane zwracane będą w tekstowym formacie XML (Extensible Markup Language).

Zwracany dokument XML składa się z elementu głównego <DirectionsResponse>, który zawsze zawiera element najwyższego poziomu o nazwie <status>, a przy powodzeniu żądania HTTP, co najmniej jeden element o nazwie <results> z których każda zawiera jeden zestaw informacji.

 

 

DirectionsResponse:

element główny zawierający zawsze element najwyższego poziomu o nazwie o nazwie <status>

<status>

zawiera status żądania HTTP i może zawierać informacje dlaczego żądanie nie zostało zrealizowane przez serwer.

Kody wyniku:

OK

Wskazuje, że nie wystąpiły żadne błędy. Adres został pomyślnie przetwarzane oraz co najmniej jeden wynik został zwrócony.

ZERO_RESULTS

wskazuje, że żądanie Geocoding było udane, ale nie przyniosło wyników. Ten problem może wystąpić, jeśli przekazany został nieistniejący adres.

OVER_QUERY_LIMIT

przekroczony został limit żądań.

REQUEST_DENIED

serwer odrzucił wykonania usługi 'Geocoding' przez Twoją aplikację.

INVALID_REQUEST

zapytanie jest nieprawidłowe, niepełne, np. brakuje parametru adres, filtr lub współrzędne LatLon)

UNKNOWN_ERROR

Żądanie nie może być obsłużone z powodu błędu serwera. Po ponowieniu, żądanie może zakończyć się powodzeniem.

<results>

zawiera dane znalezionego obiektu(ów). Każdy element <results> może składać się z następujących elementów:

 

type

element określający typ zwracanego obiektu. Może ich być kilka. Przykładowo dla obiektu:
Wawel, Kraków, PL występują trzy elementy type, które mają następującą treśc:

• museum
• point_of_interest
• establishment

a dla obiektu Kraków, Pl występują dwa elementy type, które mają wartość:

• locality
• political

formatted_address

lokalizacja obiektu, często lokalizacja jest odpowiednikiem „adresu pocztowego”, przykładowo dla pytania:Wawel, Kraków, PL element formatted_address ma treść: Zamek Królewski na Wawelu, Wawel 5, 31-001 Kraków, Polska.

address_component

Jeden, lub więcej elementów zawierajacy jednostkowe dane adresowe. Każdy element address_component zazwyczaj zawiera oddzielne jednostki adresowe, takie jak:

 

long_name

pełny opis tekstowy lub nazwa składnika adresowego.

short_name

skrócona nazwa tekstowa składnika adresu ( o ile jest dostępna).

type

Element(y) określający typ zwracanego obiektu. Może ich być kilka.

geometry

element ten zawiera dane o położeniu geograficznym obiektu i typu.

 

location

współrzędne geograficzne obiektu:

lat - szerokość geograficzna

lon - długość geograficzna

location_type

zawiera dodatkowe dane dotyczące określonej lokalizacji. Obecnie obsługiwane są poniższe

• ROOFTOP - zwrócony wynik jest dokładny, z dokładnością do domu
• RANGE_INTERPOLATED - zwrócony wynik jest przybliżony (brak jest dokładnych danych adresowych)
• GEOMETRIC_CENTER - zwrócony wynik jest geometrycznym środkiem obszaru (ulica, region, obszar).
• APPROXIMATE - zwrócony wynik jest przybliżony.

viewport

zawiera współrzędne geograficzne okna podglądu obszaru mapy zawierającego obiekt.

 

southwest

zawiera współrzędne geograficzne południowo-zachodniego narożnika okna podglądu.

 

lat- szerokość geograficzna

lng- długość geograficzna

northeast

zawiera współrzędne geograficzne północno-wschodniego narożnika okna podglądu.

 

lat- szerokość geograficzna

lng- długość geograficzna

bounds

(zwracany opcjonalnie), zawiera współrzędne geograficzne obszaru zawierającego obiekt. Nie musi pokrywać się z obszarem podglądu <viewport>.

 

southwest

zawiera współrzędne geograficzne południowo-zachodniego narożnika okna podglądu.

 

lat- szerokość geograficzna

lng- długość geograficzna

northeast

zawiera współrzędne geograficzne północno-wschodniego narożnika okna podglądu.

 

lat- szerokość geograficzna

lng- długość geograficzna

partial_match

wskazuje, że adres obiektu został dopasowany częściowo. Powodem dopasowania częściowego może być niepełny, bądź błędny adres, lub błędy ortograficzne w adresie. Częściowe dopasowanie może być także zwrócone, gdy adres jest niejednoznaczny, np. wskazuje na dwa, lub więcej miejsc w obszarze przeszukiwania. Należy pamiętać, że jeżeli adres jest nieprawidłowy, zwrócony może być alternatywny adres.

place_id

unikatowy identyfikator przypisany do obiektu w bazie danych Google Places i Google Maps.