Instagram-Nutzer*innen-Insights

Stellt Kennzahlen zu sozialer Interaktion für eine*n Instagram-Nutzer*in dar.

Erstellen

Dieser Vorgang wird nicht unterstützt.

Lesen

GET /{ig-user-id}/insights

Gibt Insights zu einem IG-Nutzer zurück.

Einschränkungen

• follower_count, online_followers und alle audience_*-Kennzahlen sind für IG-Nutzer*innen mit weniger als 100 Follower*innen nicht verfügbar.
• Insights-Daten für die Kennzahl online_followers sind nur für die letzten 30 Tage verfügbar.
• Wenn von dir angeforderte Insights-Daten nicht existieren oder aktuell nicht verfügbar sind, gibt die API anstatt 0 für einzelne Kennzahlen einen leeren Datensatz zurück.
• Demografische Kennzahlen geben nur die 45 besten Ergebnisse zurück (z. B. für audience_city können bis zu 45 Städte mit der höchsten Anzahl von Follower*innen zurückgegeben werden).
• Bei Berechnungen für demografische Kennzahlen werden nur Betrachter*innen berücksichtigt, für die uns demografische Daten vorliegen.
• Als Summe demografischer Kennzahlenwerte kann sich ein Wert ergeben, der unter der Anzahl der Follower*innen liegt (siehe vorheriger Punkt).
• audience_*-Kennzahlen unterstützen die Zeitraum-Parameter since und until nicht.
• Daten, die zur Berechnung von Kennzahlen verwendet werden, können sich bis zu 48 Stunden verzögern.

Anforderungen

Anfragesyntax

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &since={since}
  &until={until}
  &access_token={access-token}

Pfadparameter

Abfrage-String-Parameter

Kennzahlen und Perioden

Die Ergebnisse von Kennzahlen, die lifetime-Perioden unterstützen, werden in einem Array von 24-Stunden-Perioden zurückgegeben, wobei die Perioden um UTC–07:00 enden. audience_*-Kennzahlen unterstützen die Zeitraum-Parameter since und until nicht.

Zeitraum

Diese Edge unterstützt die zeitbasierte Paginierung. Du kannst also die Parameter since und until in Unix-Zeitstempel einschließen, um einen Zeitraum zu definieren. Beispiel: Wenn du Impressions für 28 Tage abrufen möchtest – jeder Tag für die letzten 10 Tage – kannst du Unix-Zeitstempel für vor 10 Tagen und heute generieren, diese den Parametern since und until zuweisen und in deine Anfrage einschließen:

metric=impressions&period=days_28&since=1501545600&until=1502493720

Die Parameter since und until sind inklusiv, d. h.: Wenn dein Zeitraum einen Tag umfasst, der noch nicht zu Ende ist (also heute), können bei nachfolgenden Abfragen an diesem Tag höhere Werte zurückgegeben werden. Wenn du die Parameter since und until nicht einschließt, verwendet die API standardmäßig einen 2-Tage-Zeitraum: gestern bis heute.

Beispielanfrage

curl -X GET \
  'https://graph.facebook.com/v19.0/17841405822304914/insights?metric=impressions,reach,profile_views&period=day&access_token=IGQVJ...'

Beispielantwort

{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 4,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 66,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "Total number of times this profile has been seen",
      "id": "17841400008460056/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 3,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 36,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen this profile",
      "id": "17841400008460056/insights/reach/day"
    },
    {
      "name": "profile_views",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 2,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Profile Views",
      "description": "Total number of unique accounts that have viewed this profile within the specified period",
      "id": "17841400008460056/insights/profile_views/day"
    }
  ]
}

Beachte, dass in der oben aufgeführten Beispielanfrage die Parameter since und until nicht enthalten sind. Daher hat die API Daten für den Standardzeitraum von 2 Tagen zurückgegeben. Jeder Tag wird durch einen UTC-Zeitstempel im ISO 8601-Format mit einem Offset von null angegeben, der einer end_time-Eigenschaft zugewiesen wurde.

Die Eigenschaft end_time gibt den Rückblick-Stichtag eines Datensatzes an. Daten, die älter sind als dieser Wert, werden nicht in die Berechnung des Datensatzes eingeschlossen.

Aktualisieren

Dieser Vorgang wird nicht unterstützt.

Löschen

Dieser Vorgang wird nicht unterstützt.

Neue Kennzahlen

Anfragesyntax

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &timeframe={timeframe}
  &metric_type={metric-type}
  &breakdown={breakdown}
  &since={since}
  &until={until}
  &access_token={access-token}

Pfadparameter

Abfrage-String-Parameter

Aufschlüsselung

Wenn du metric_type=total_value abfragst, kannst du auch eine oder mehrere Aufschlüsselungen festlegen. Die Ergebnisse werden dann anhand der festgelegten Aufschlüsselung in kleinere Teile unterteilt. Zulässige Werte sind:

• contact_button_type – Ergebnisse nach UI-Komponente des Profils aufschlüsseln, auf die Betrachter*innen getippt oder geklickt haben. Zulässige Antwortwerte:

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type – Ergebnisse nach Follower*innen und Personen, die keine Follower*innen sind, aufschlüsseln. Zulässige Antwortwerte sind:

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type – Ergebnisse nach der Oberfläche aufschlüsseln, in der Betrachter*innen das Medium des*der App-Nutzer*in angesehen oder mit ihm interagiert haben. Zulässige Antwortwerte sind:

  • AD
  • FEED
  • REELS
  • STORY

Beachte die Kennzahlen-Tabelle, um festzustellen, welche Kennzahlen mit einer Aufschlüsselung kompatibel sind. Wenn du eine Kennzahl anforderst, die keine Aufschlüsselungen unterstützt, gibt die API eine Fehlermeldung zurück ("An unknown error has occurred."). Sei also vorsichtig, wenn du mehrere Kennzahlen in einer einzigen Anfrage anforderst.

Wenn du metric_type=time_series abfragst, sind in der Antwort keine Aufschlüsselungen enthalten.

Kennzahlentyp

Du kannst angeben, wie Ergebnisse aggregiert werden sollen: nach Zeitraum oder als einfache Gesamtzahl (mit Aufschlüsselungen, falls gewünscht). Zulässige Werte sind:

• time_series – Teilt der API mit, Ergebnisse nach Zeitraum zu aggregieren. Siehe Zeitraum.
• total_value – Teilt der API mit, Ergebnisse als einfache Gesamtzahl zurückzugeben. Wenn du Aufschlüsselungen in die Abfrage einbeziehst, werden die Ergebnisse basierend auf den entsprechenden Aufschlüsselungen unterteilt. Siehe Aufschlüsselung.

Periode

Teilt der API mit, welcher zeitliche Rahmen beim Aggregieren der Ergebnisse verwendet werden soll. Nur kompatibel mit Kennzahlen zu Interaktionen.

Zeitlicher Rahmen

Teilt der API mit, wie weit bei der Abfrage von Kennzahlen zu demografischen Daten in die Vergangenheit geblickt werden soll. Dieser Wert überschreibt die Parameter since und until.

Zeitraum

Weise den Parametern since und until Unix-Zeitstempel zu, um eine Zeitspanne zu definieren. Die API bezieht nur Daten ein, die innerhalb dieser Zeitspanne erstellt wurden. Wenn du diese Parameter nicht einbeziehst, verwendet die API Daten der letzten 24 Stunden.

Für Kennzahlen zu demografischen Daten überschreibt der timeframe-Parameter diese Werte. Siehe Zeitlicher Rahmen.

Kennzahlen

Interaktionskennzahlen

Demografische Kennzahlen

Antwort

Ein JSON-Objekt, das die Ergebnisse deiner Anfrage enthält. Die Ergebnisse können je nach deiner Anfragespezifikation die folgenden Daten enthalten:

{
  "data": [
    {
      "name": "{data}",
      "period": "{period}",
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value": {value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{key-1}",
              "{key-2",
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "{value-1}",
                  "{value-2}",
                  ...
                ],
                "value": {value},
                "end_time": "{end-time}"
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ],
  "paging": {
    "previous": "{previous}",
    "next": "{next}"
  }
}

Antwortinhalt

Beispielabfrage von Interaktionskennzahlen

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..."

Beispielantwort zu Interaktionskennzahlen

{
  "data": [
    {
      "name": "reach",
      "period": "day",
      "title": "Accounts reached",
      "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.",
      "total_value": {
        "value": 224,
        "breakdowns": [
          {
            "dimension_keys": [
              "media_product_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "CAROUSEL_CONTAINER"
                ],
                "value": 100
              },
              {
                "dimension_values": [
                  "POST"
                ],
                "value": 124
              }
            ]
          }
        ]
      },
      "id": "17841405309211844/insights/reach/day"
    }
  ],
  "paging": {
    "previous": "https://graph.face...",
    "next": "https://graph.face..."
  }

Beispielabfrage von demografischen Kennzahlen

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..."

Beispielantwort zu demografischen Kennzahlen

{
  "data": [
    {
      "name": "engaged_audience_demographics",
      "period": "lifetime",
      "title": "Engaged audience demographics",
      "description": "The demographic characteristics of the engaged audience, including countries, cities and gender distribution.",
      "total_value": {
        "breakdowns": [
          {
            "dimension_keys": [
              "timeframe",
              "country"
            ],
            "results": [
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "AR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "RU"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "LA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "IQ"
                ],
                "value": 2
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MX"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "FR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "ES"
                ],
                "value": 3
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "NL"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "TR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "US"
                ],
                "value": 7
              }
            ]
          }
        ]
      },
      "id": "17841401130346306/insights/engaged_audience_demographics/lifetime"
    }
  ]
}