Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Dados demográficos de seguidores no Instagram através da API

O endpoint de insights da conta do Instagram devolve dados demográficos de seguidores com metric=follower_demographics, period=lifetime, metric_type=total_value, um timeframe e uma desagregação por idade, género, cidade ou país. engaged_audience_demographics faz o mesmo para as contas que interagiram com o conteúdo. A Meta devolve apenas os 45 valores principais; os dados de seguidores exigem 100 seguidores, e os dados de público envolvido exigem 100 interações no timeframe.

O easyCoexistence lê os dados demográficos de seguidores e de público envolvido do Instagram com get_social_insights, para que o Claude, o ChatGPT ou o seu próprio código possam perguntar que países, cidades ou escalões etários seguem a conta e obter os números da Meta para a conta ligada.

100 followers

Abaixo deste valor, follower_demographics não é devolvido para a conta.

100 engagements

Interações necessárias no timeframe para que engaged_audience_demographics seja devolvido.

Top 45

As métricas demográficas devolvem apenas os 45 valores principais, pelo que as cidades e países mais pequenos ficam de fora.

19 Aug 2024

last_14_days, last_30_days, last_90_days e prev_month deixaram de funcionar para engaged_audience_demographics em todas as versões.

48 hours

Quanto tempo podem atrasar os dados por trás das métricas da conta.

Que métricas demográficas existem?

Duas no referência de insights da conta da Meta, ambas lidas com GET /<IG_ID>/insights, e dois conjuntos antigos que o código antigo ainda pede:

  • follower_demographics: as características demográficas dos seguidores da conta.
  • engaged_audience_demographics: o mesmo para o público envolvido, as contas que interagiram com o conteúdo.
  • Ambas: period lifetime, metric_type total_value, um timeframe e uma desagregação por idade, cidade, país ou género.
  • audience_gender_age, audience_locale, audience_country e audience_city: descontinuadas a 11 de dezembro de 2023.
  • reached_audience_demographics: mencionada no changelog de 2024 da Meta, mas ausente da tabela de métricas atual.

Como se pedem os dados demográficos de seguidores?

Com a métrica, period=lifetime, metric_type=total_value, um timeframe e uma única desagregação. O timeframe substitui since e until, que as métricas demográficas não suportam, e é obrigatório. Com o Instagram Login, o token precisa de instagram_business_basic e instagram_business_manage_insights, e o pedido vai para graph.instagram.com:

Followers by country, this month
GET https://graph.instagram.com/<IG_ID>/insights
  ?metric=follower_demographics
  &period=lifetime
  &timeframe=this_month
  &breakdown=country
  &metric_type=total_value
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

Como é a resposta?

As contagens estão em total_value.breakdowns. dimension_keys indica o timeframe e a desagregação pedidos, e cada resultado associa dimension_values, o timeframe e um valor da desagregação, com uma contagem. O exemplo da Meta, para o público envolvido por país, devolve os países como códigos de duas letras, como US e ES:

The response shape, broken down by country
{
  "data": [
    {
      "name": "follower_demographics",
      "period": "lifetime",
      "title": "<TITLE>",
      "description": "<DESCRIPTION>",
      "total_value": {
        "breakdowns": [
          {
            "dimension_keys": ["timeframe", "country"],
            "results": [
              { "dimension_values": ["<TIMEFRAME>", "<COUNTRY_CODE>"], "value": <COUNT> },
              { "dimension_values": ["<TIMEFRAME>", "<COUNTRY_CODE>"], "value": <COUNT> }
            ]
          }
        ]
      },
      "id": "<IG_ID>/insights/follower_demographics/lifetime"
    }
  ]
}

Que timeframes funcionam?

A referência da Meta indica last_14_days, last_30_days, last_90_days, prev_month, this_month e this_week para ambas as métricas e, para o público envolvido, descreve this_month como os últimos 30 dias e this_week como os últimos 7. Para engaged_audience_demographics, os primeiros quatro deixaram de funcionar a partir da v20.0 e em todas as versões a 19 de agosto de 2024, por isso utilize this_week ou this_month; essa entrada do changelog não menciona follower_demographics.

Que limiares e limites se aplicam?

A referência de insights da conta da Meta define estas regras para as métricas demográficas:

  • follower_demographics não é devolvido para uma conta com menos de 100 seguidores.
  • engaged_audience_demographics não é devolvido com menos de 100 interações no timeframe.
  • Só são devolvidos os 45 valores principais, pelo que as cidades e países mais pequenos ficam de fora.
  • Só são contados os visualizadores com dados demográficos, pelo que os valores podem somar menos do que o número de seguidores.
  • Dados em falta devolvem um conjunto vazio, não 0, e os dados podem atrasar até 48 horas.
  • Uma desagregação que a métrica pedida não suporta faz falhar a chamada inteira com An unknown error has occurred.

Os dados demográficos funcionam com o Instagram Login?

Sim. A Meta abriu os insights de conta e de conteúdos às aplicações do Instagram Login a 21 de janeiro de 2025, e a referência de insights da conta lista o Instagram Login com as permissões instagram_business_basic e instagram_business_manage_insights e graph.instagram.com como host. A conta tem de ser uma conta profissional ou de criador, como exige a Plataforma Instagram da Meta.

Como é que o get_social_insights lê os dados demográficos?

Com metrics definido como follower_demographics ou engaged_audience_demographics, period definido como lifetime e params com timeframe, breakdown e metric_type. O easyCoexistence chama GET /<IG_ID>/insights para a conta ligada com o seu token e devolve a resposta da Meta, para que o Claude ou o ChatGPT possam dizer que países, cidades ou escalões etários seguem a conta.

get_social_insights arguments for followers by age
{
  "account_id": "<ACCOUNT_ID>",
  "metrics": ["follower_demographics"],
  "period": "lifetime",
  "params": {
    "timeframe": "this_month",
    "breakdown": "age",
    "metric_type": "total_value"
  }
}

Erros comuns

  • Passar since e until. As métricas demográficas não os suportam: o timeframe define o intervalo, e é obrigatório.
  • Usar last_30_days ou last_90_days para o público envolvido. Esses timeframes deixaram de funcionar para engaged_audience_demographics em todas as versões a 19 de agosto de 2024.
  • Somar uma desagregação para obter o número de seguidores. Só são contados os visualizadores com dados demográficos e só são devolvidos os 45 valores principais, pelo que a soma fica aquém.
  • Esperar dados de uma conta pequena. Os dados demográficos de seguidores exigem 100 seguidores, e o público envolvido 100 interações no timeframe.
Fazer isto com a EasyCoexistence

De US$ 9 a US$ 0.75 por número ligado por mês, descendo à medida que adiciona números, com os primeiros 3 dias grátis.

Perguntas frequentes

Quantos seguidores uma conta do Instagram precisa para ter dados demográficos?

100. Abaixo disso, a Meta não devolve follower_demographics; engaged_audience_demographics exige 100 interações no timeframe.

Porque é que o Instagram devolve apenas 45 cidades?

As métricas demográficas da Meta devolvem apenas os 45 valores principais, pelo que as cidades e países mais pequenos ficam de fora.

O que substituiu audience_gender_age na API do Instagram?

follower_demographics, com uma desagregação por idade, género, cidade ou país. A Meta descontinuou audience_gender_age, audience_locale, audience_country e audience_city a 11 de dezembro de 2023.

Posso usar since e until com follower_demographics?

Não. As métricas demográficas não suportam since e until; o parâmetro timeframe define o intervalo em vez disso, e é obrigatório.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em