Insight sugli utenti di Instagram

Rappresentano le metriche delle interazioni social su un utente di Instagram.

Creazione

Questa operazione non è supportata.

Lettura

GET /{ig-user-id}/insights

Restituisce gli insights su un utente di IG.

Limitazioni

• follower_count, online_followers e tutte le metriche audience_* non sono disponibili su utenti di IG con meno di 100 follower.
• Gli insight per la metrica online_followers sono disponibili solo per gli ultimi 30 giorni.
• Se i dati di insight che stai richiedendo non esistono o non sono attualmente disponibili, l'API restituirà un set di dati vuoto invece di 0 per le singole metriche.
• Le metriche demografiche restituiscono solo i 45 performer migliori (ad esempio, per audience_city, possono essere restituite fino a 45 città con il maggior numero di follower).
• Solo gli spettatori per i quali disponiamo di dati demografici vengono utilizzati nei calcoli delle metriche demografiche.
• La somma dei valori delle metriche demografiche può restituire un valore inferiore al numero dei follower (vedi punto elenco precedente).
• Le metricheaudience_* non supportano i parametri intervallosince e until.
• I dati utilizzati per calcolare le metriche possono essere ritardati fino a 48 ore.

Requisiti

Sintassi della richiesta

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

Parametri del percorso

Parametri della stringa della query

Metriche e periodi

Le metriche che supportano i periodi lifetime restituiranno i risultati in un array di periodi di 24 ore, con i periodi che terminano ad UTC−07:00. Le metriche audience_* non supportano i parametri intervallosince e until.

Intervallo

Questo segmento supporta la paginazione basata sul tempo, quindi puoi includere i parametri since e until con marche temporali Unix per definire un intervallo. Ad esempio, per ottenere 28 giorni di impression, ogni giorno negli ultimi 10 giorni, potresti generare marche temporali Unix per 10 giorni fa e per oggi, assegnarle ai parametri since e until e includerle nella richiesta:

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

I parametri since e until sono inclusivi, quindi se l'intervallo include un giorno che non è terminato (ovvero, oggi), le query successive nel corso della giornata potrebbero restituire valori aumentati. Se non includi i parametri since e until, l'API utilizza per impostazione predefinita un intervallo di 2 giorni: da ieri a oggi.

Esempio di richiesta

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

Esempio di risposta

{
  "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"
    }
  ]
}

L'esempio di richiesta sopra non includeva i parametri since e until, quindi l'API ha restituito dati per un intervallo predefinito di 2 giorni. Ogni giorno è identificato da una marca temporale UTC in formato ISO 8601 con offset zero, che è stata assegnata a una proprietà end_time.

La proprietà end_time indica la data limite di ricerca di un set di dati; i dati più vecchi di questo valore non sono inclusi nel calcolo del set di dati.

Aggiornamento

Questa operazione non è supportata.

Eliminazione

Questa operazione non è supportata.

Nuove metriche

Sintassi della richiesta

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}

Parametri del percorso

Parametri della stringa della query

Dettagli

Richiedendo metric_type=total_value, puoi anche specificare uno o più dettagli e i risultati saranno ripartiti in gruppi più piccoli sulla base del dettaglio specificato. I valori possono essere:

• contact_button_type: risultati dei dettagli in base al componente dell'interfaccia utente del profilo che è stato toccato o cliccato dagli spettatori. I valori delle risposte possono essere:

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type: risultati dei dettagli in base a follower e non follower. I valori delle risposte possono essere:

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type: risultati dei dettagli in base alla piattaforma su cui gli spettatori hanno visualizzato o interagito con il contenuto multimediale dell'utente dell'app. I valori delle risposte possono essere:

  • AD
  • FEED
  • REELS
  • STORY

Consulta la tabella Metriche per determinare quali metriche sono compatibili con un dato dettaglio. Richiedendo una metrica che non supporta un dato dettaglio, l'API restituirà un errore (An unknown error has occurred.), quindi fai attenzione quando richiedi più metriche in una singola query.

Richiedendo metric_type=time_series, i dettagli non saranno inclusi nella risposta.

Tipo di metrica

Puoi designare come desideri che siano aggregati i risultati, se per periodo di tempo o come semplice totale (con dettagli, se richiesto). I valori possono essere:

• time_series: dice all'API di aggregare i risultati per periodo di tempo. Consulta Periodo.
• total_value: dice all'API di restituire i risultati come semplice totale. Se nella richiesta sono inclusi i dettagli, i gruppi di risultati saranno ulteriormente suddivisi per dettagli specifici. Consulta Dettagli.

Periodo

Dice all'API quale intervallo usare in fase di aggregazione dei risultati. Compatibile solo con le metriche correlate all'interazione.

Intervallo di tempo

Dice all'API quanto indietro nel tempo ricercare i dati quando si richiedono metriche correlate ai dati demografici. Questo valore sovrascrive i parametri since e until.

Intervallo

Assegna marche temporali UNIX ai parametri since e until per definire un intervallo. L'API includerà solo i dati creati in questo intervallo (inclusi inizio e fine). Se non includi questi parametri, l'API effettuerà la ricerca nelle 24 ore precedenti.

Per le metriche correlate ai dati demografici, il parametro timeframe sovrascrive questi valori. Consulta Intervallo di tempo.

Metriche

Metriche di interazione

Metriche demografiche

Risposta

Un oggetto JSON che contiene i risultati della tua query. I risultati potrebbero includere i dati seguenti, sulla base delle specifiche della tua query:

{
  "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}"
  }
}

Contenuti della risposta

Esempio di richiesta di metrica di interazione

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..."

Esempio di risposta di metrica di interazione

{
  "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..."
  }

Esempio di richiesta di metrica demografica

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..."

Esempio di risposta di metrica demografica

{
  "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"
    }
  ]
}