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 qualitativ hochwertige Fotos hinzufügen können. Mit „Ortsfotos (neu)“ 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 Fotorressourcen für relevante Fotos anfordern. Mit „Place Photos (New)“ können Sie dann 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 Liveanfragen 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 in folgendem 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 Parameter maxHeightPx, den Parameter maxWidthPx oder beide.

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

Erforderliche Parameter

Fotoname

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

Ein Beispiel finden Sie unter Fotonamen abrufen.

maxHeightPx und maxWidthPx

Gibt die maximale beabsichtigte 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 Attribute „maxheight“ und „maxwidth“ ist eine Ganzzahl zwischen 1 und 4800 zulässig.

Sie müssen entweder maxHeightPx oder maxWidthPx oder beides angeben.

Optionale Parameter

skipHttpRedirect

Wenn false (Standard) festgelegt ist, wird eine HTTP-Weiterleitung zum Bild ausgeführt, um das Bild zurückzugeben. Wenn true, überspringen Sie die Weiterleitung und geben Sie eine JSON-Antwort mit den Bilddetails zurück. 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 Fotoressourcennamen 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 Zuordnungen bereits im Bild eingebunden. Wenn das zurückgegebene photo-Element jedoch einen Wert im Feld authorAttributions enthält, müssen Sie die zusätzliche Zuordnung immer dann in Ihre Anwendung einbinden, wenn das Bild zu sehen ist.

Das folgende Beispiel zeigt eine „Place Details (New)“-Anfrage, die photos in der Feldmaske enthält, 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
 Unten sehen Sie ein Beispiel für ein photos[]-Array in der Antwort. 
    ...
    "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"
          }
        ]
      },
    ...

Ein Foto eines Orts anfordern

Die Beispielanfrage unten gibt ein Bild mit der Ressource 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

Bei Place Photos (New)-Anfragen können die folgenden Fehlercodes zurückgegeben werden.

Kontingent überschritten (403)

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

Benachrichtigung „Kontingent wurde überschritten“

Ungültige Anfrage (404)

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

  • Der angegebene Name des Fotos ist nicht korrekt.
  • Die Anfrage enthielt nicht den Parameter maxHeightPx oder maxWidthPx.
  • Der Wert des Parameters maxHeightPx oder maxWidthtPx wurde auf null festgelegt.
  • name ist abgelaufen. Wenn name abläuft, senden 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 gleichzeitig 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 fordern Sie eine Kontingenterhöhung an.

Testen!

Mit dem API 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. Setzen Sie den Parameter name auf: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Setzen Sie skipHttpRedirect auf true, damit die Anfrage eine JSON-Antwort zurückgibt. Standardmäßig wird mit der Anfrage das Bild zurückgegeben, das von API Explorer nicht angezeigt werden kann.
  4. Klicken Sie auf die Schaltfläche Ausführen. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  5. Wählen Sie im Bereich „API Explorer“ das Vollbildsymbol  aus, um das API Explorer-Fenster zu maximieren.