Zdjęcia miejsc (nowe)

Wybierz platformę: Android iOS Usługa internetowa
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Usługa Place Photos (New) to interfejs API tylko do odczytu, który umożliwia dodawanie do aplikacji wysokiej jakości treści fotograficznych. Zdjęcia miejsca (nowa funkcja) zapewniają dostęp do milionów zdjęć przechowywanych w bazie danych Miejsca.

Gdy uzyskujesz informacje o miejscach za pomocą żądań Szczegóły miejsca (Nowe), Wyszukiwanie w pobliżu (Nowe) lub Wyszukiwanie tekstowe (Nowe), możesz też poprosić o zasoby fotograficzne dotyczące odpowiednich treści fotograficznych. Za pomocą funkcji umieszczania zdjęć (Nowa) możesz uzyskać dostęp do zdjęć referencyjnych i zmienić ich rozmiar na optymalny dla Twojej aplikacji.

Narzędzie APIs Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:

Zdjęcia miejsca (nowe)

Żądanie dotyczące zdjęć miejsc (nowych) to żądanie HTTP GET do adresu URL w formie: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Wymagane są następujące parametry:

  • NAME zawiera nazwę zasobu zdjęcia.
  • API_KEY zawiera klucz interfejsu API.
  • PARAMETERS zawiera parametr maxHeightPx, parametr maxWidthPx lub oba te parametry.

Pełna lista wymaganych i opcjonalnych parametrów została podana poniżej.

Wymagane parametry

Nazwa zdjęcia

Identyfikator ciągu znaków, który jednoznacznie identyfikuje zdjęcie. Nazwy zdjęć są zwracane z żądania Szczegóły miejsca (nowe), Wyszukiwanie w pobliżu (nowe) lub Wyszukiwanie tekstu (nowe) w właściwości name każdego elementu tablicy photos[].

Przykład znajdziesz w sekcji Pobieranie nazwy zdjęcia.

maxHeightPx i maxWidthPx

Określa maksymalną docelową wysokość i szerokość obrazu w pikselach. Jeśli obraz jest mniejszy niż określone wartości, zwrócony zostanie oryginalny obraz. Jeśli obraz jest większy w jednym z wymiarów, zostanie przeskalowany, aby pasował do mniejszego z tych wymiarów, zachowując oryginalny format. Właściwości maxheight i maxwidth akceptują liczby całkowite z zakresu od 1 do 4800.

Musisz podać wartość maxHeightPx, maxWidthPx lub obie te wartości.

Parametry opcjonalne

skipHttpRedirect

Jeśli false (domyślnie), przekieruj HTTP do obrazu, aby go zwrócić. Jeśli true, pomiń przekierowanie i zwróć odpowiedź JSON zawierającą szczegóły obrazu. Na przykład:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

Ta opcja jest ignorowana w przypadku żądań innych niż HTTP.

Pobieranie nazwy zdjęcia

Wszystkie żądania dotyczące Zdjęć miejsca (Nowe) muszą zawierać nazwę zasobu zdjęcia zwróconą w odpowiedzi na żądanie wyszukiwania w pobliżu (Nowe), wyszukiwania tekstowego (Nowe) lub Szczegóły miejsca (Nowe). Odpowiedź na te żądania zawiera tablicę photos[], jeśli miejsce ma powiązane treści fotograficzne.

Każdy element photo[] zawiera te pola:

  • name – ciąg tekstowy zawierający nazwę zasobu zdjęcia, gdy wykonujesz żądanie dotyczące zdjęcia. Ten ciąg ma postać:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx – maksymalna wysokość obrazu w pikselach.
  • widthPx – maksymalna szerokość obrazu w pikselach.
  • authorAttributions[] – wszelkie wymagane informacje o autorze. To pole jest zawsze obecne, ale może być puste.

Zdjęcia zwracane przez funkcję Zdjęcia miejsca (Nowe) pochodzą z różnych źródeł, w tym od właścicieli firm i użytkowników. W większości przypadków można używać tych zdjęć bez przypisów, ale mogą one zawierać wymagane informacje. Jeśli jednak zwrócony element photo zawiera wartość w polu authorAttributions, musisz dodać dodatkowe informacje o źródle w aplikacji w miejscu wyświetlania obrazu.

Ten przykład pokazuje żądanie Szczegóły miejsca (Nowe), które zawiera w masce pola photos, dzięki czemu odpowiedź zawiera tablicę photos[]:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 Poniżej znajdziesz przykład tablicy photos[] w odpowiedzi. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },    ...

Prośba o zdjęcie miejsca

Przykładowe żądanie poniżej zwraca obraz za pomocą zasobu name, zmieniając jego rozmiar tak, aby miał co najwyżej 400 pikseli wysokości i szerokości:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

Odpowiedź na udaną prośbę o umieszczeniu zdjęć (nowa) to obraz. Typ obrazu zależy od typu pierwotnie przesłanego zdjęcia.

Kody błędów

Żądania dotyczące usługi Place Photos (New) mogą zwracać te kody błędów.

Przekroczony limit miejsca (403)

Jeśli żądanie przekracza dostępną pulę, serwer zwraca stan HTTP 403 i wyświetla ten obraz, aby wskazać, że limit został przekroczony:

Powiadomienie o przekroczeniu limitu

Nieprawidłowe żądanie (404)

Jeśli serwer nie może zrozumieć żądania, zwraca kod stanu HTTP 400, który wskazuje na nieprawidłowe żądanie. Najczęstsze przyczyny nieprawidłowego żądania to:

Zbyt wiele żądań (429)

Google zaleca wczytywanie zdjęć na żądanie. Jeśli spróbujesz wyświetlić wszystkie obrazy danego miejsca naraz, serwer może zwrócić stan HTTP 429, wskazujący, że wczytano zbyt wiele zdjęć naraz. Jeśli pojawi się ten komunikat o błędzie, skontaktuj się z zespołem pomocy i poproś o zwiększenie limitu.

Wypróbuj

Narzędzie API Explorer umożliwia wysyłanie przykładowych żądań, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami.

Aby poprosić o zatwierdzenie:

  1. Po prawej stronie strony kliknij ikonę interfejsu API .
  2. Ustaw parametr name na: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Ustaw wartość skipHttpRedirect na true, aby żądanie zwracało odpowiedź w formacie JSON. Domyślnie żądanie zwraca obraz, którego nie można wyświetlić w Eksploratorze interfejsu API.
  4. Kliknij przycisk Wykonaj. W oknie wybierz konto, którego chcesz użyć do wysłania żądania.

  5. W panelu API Explorer kliknij ikonę pełnego ekranu , aby rozwinąć okno.