Ortsfotos (neu)

Plattform auswählen: Android iOS Webdienst
Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

Der Dienst „Place Photos (New)“ ist eine schreibgeschützte API, mit der Sie Ihrer Anwendung hochwertige Fotos hinzufügen können. Mit „Place Photos (New)“ haben Sie Zugriff auf Millionen von Fotos, die in der Places-Datenbank gespeichert sind.

Wenn Sie über eine „Place Details (New)“-, „Nearby Search (New)“- oder „Text Search (New)“-Anfrage Informationen zum Ort abrufen, können Sie auch Fotoressourcen für relevante Fotos anfordern. Mit „Place Photos (New)“ können Sie auf die referenzierten Fotos zugreifen und das Bild auf die für Ihre Anwendung optimale Größe skalieren.

Mit dem APIs Explorer können Sie Live-Anfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:

„Place Photos (New)“-Anfragen

Eine „Place Photos (New)“-Anfrage ist eine HTTP/GET-Anfrage an eine URL im folgenden Format: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Dabei sind die folgenden Parameter erforderlich:

  • NAME enthält den Ressourcennamen des Fotos.
  • API_KEY enthält den API-Schlüssel.
  • PARAMETERS enthält entweder den maxHeightPx Parameter, den maxWidthPx Parameter oder beide.

Die vollständige Liste der erforderlichen und optionalen Parameter wird unten beschrieben.

Erforderliche Parameter

Fotoname

Ein String, der ein Foto eindeutig identifiziert. Fotonamen werden von einer „Place Details (New)“, „Nearby Search (New)“, oder „Text Search (New)“ -Anfrage in der name Eigenschaft jedes Elements des photos[] Arrays zurückgegeben.

Ein Beispiel finden Sie unter Fotonamen abrufen.

maxHeightPx und maxWidthPx

Gibt die maximale Höhe und Breite des Bildes in Pixeln an. Wenn das Bild kleiner als die angegebenen Werte ist, wird das Originalbild zurückgegeben. Wenn das Bild in einer der beiden Dimensionen größer ist, wird es so skaliert, dass es der kleineren der beiden Dimensionen entspricht, wobei das ursprüngliche Seitenverhältnis beibehalten wird. Für die Eigenschaften „maxheight“ und „maxwidth“ kann eine Ganzzahl zwischen 1 und 4800 angegeben werden.

Sie müssen entweder maxHeightPx, maxWidthPx oder beide angeben.

Optionale Parameter

skipHttpRedirect

Wenn false (Standard), wird eine HTTP-Weiterleitung zum Bild ausgeführt, um das Bild zurückzugeben. Wenn true, wird die Weiterleitung übersprungen und eine JSON-Antwort mit den Bilddetails zurückgegeben. Beispiel:

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

Diese Option wird für Nicht-HTTP-Anfragen ignoriert.

Fotonamen abrufen

Alle Anfragen an „Place Photos (New)“ müssen einen Ressourcennamen für das Foto enthalten, der in der Antwort auf eine „Nearby Search (New)“-, „Text Search (New)“- oder „Place Details (New)“-Anfrage zurückgegeben wird. Die Antwort auf diese Anfragen enthält ein photos[]-Array, wenn der Ort zugehörige Fotos hat.

Jedes Element von photo[] enthält die folgenden Felder:

  • name : Ein String mit dem Ressourcennamen des Fotos, wenn Sie eine Fotoanfrage stellen. Dieser String hat das folgende Format:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx : Die maximale Höhe des Bildes in Pixeln.
  • widthPx : Die maximale Breite des Bildes in Pixeln.
  • authorAttributions[] : Alle erforderlichen Quellenangaben. Dieses Feld ist immer vorhanden, kann aber leer sein.

Die von „Place Photos (New)“ zurückgegebenen Fotos stammen aus unterschiedlichen Quellen, z. B. von Geschäftsinhabern oder Nutzern. In den meisten Fällen dürfen diese Fotos ohne Quellenangabe verwendet werden bzw. sind die erforderlichen Quellenangaben bereits im Bild eingebunden. Wenn das zurückgegebene photo-Element jedoch einen Wert im Feld authorAttributions enthält, müssen Sie die zusätzliche Quellenangabe immer dann in Ihre Anwendung einbinden, wenn das Bild zu sehen ist.

Das folgende Beispiel zeigt eine „Place Details (New)“-Anfrage, die enthält photos in der Feldmaske, sodass die Antwort das photos[] Array enthält:

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
 Ein Beispiel für ein photos[]-Array in der Antwort sehen Sie unten. 
    ...
    "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"
          }
        ]
      },
    ...

Ortsfoto anfordern

Die folgende Beispielanfrage gibt ein Bild anhand seines Ressourcennamens name zurück und ändert die Größe so, dass es maximal 400 Pixel hoch und breit ist:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

Die Antwort auf eine erfolgreiche „Place Photos (New)“-Anfrage ist ein Bild.

Fehlercodes

„Place Photos (New)“-Anfragen können die folgenden Fehlercodes zurückgeben.

Kontingent überschritten (403)

Wenn Ihre Anfrage Ihr verfügbares Kontingent überschreitet, gibt der Server den HTTP-Status 403 zurück und zeigt das folgende Bild an, um darauf hinzuweisen, dass das Kontingent überschritten wurde:

Benachrichtigung „Kontingent wurde überschritten“

Ungültige Anfrage (400)

Wenn der Server Ihre Anfrage nicht verarbeiten kann, gibt er den HTTP-Status 400 zurück, der auf eine ungültige Anfrage hinweist. Die häufigsten Gründe für eine ungültige Anfrage sind:

  • Der angegebene Fotoname wurde nicht korrekt angegeben.
  • Die Anfrage enthielt nicht den maxHeightPx oder den maxWidthPx Parameter.
  • Der Wert des maxHeightPx oder des maxWidthtPx Parameters wurde auf null gesetzt.
  • Der name ist abgelaufen. Wenn name abläuft, stellen Sie eine Anfrage an „Place Details (New)“, „Nearby Search (New)“ oder „Text Search (New)“, um ein neues name zu erhalten.

Zu viele Anfragen (429)

Google empfiehlt, Fotos bei Bedarf zu laden. Wenn Sie versuchen, alle Bilder für einen Ort auf einmal anzuzeigen, gibt der Server möglicherweise den HTTP-Status 429 zurück, der darauf hinweist, dass zu viele Fotos gleichzeitig geladen werden. Wenn Sie diese Fehlermeldung erhalten, wenden Sie sich an den Support und beantragen Sie eine Kontingenterhöhung.

Testen!

Mit dem APIs Explorer können Sie Beispielanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen.

So stellen Sie eine Anfrage:

  1. Wählen Sie rechts auf der Seite das API-Symbol aus.
  2. Legen Sie den Parameter name auf Folgendes fest: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Setzen Sie skipHttpRedirect auf true, damit die Anfrage eine JSON Antwort zurückgibt. Standardmäßig gibt die Anfrage das Bild zurück, das vom APIs Explorer nicht angezeigt werden kann.
  4. Wählen Sie die Schaltfläche Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  5. Wählen Sie im Bereich „APIs Explorer“ das Symbol für den Vollbildmodus aus, um das Fenster „APIs Explorer“ zu maximieren.