Pular para o conteúdo principal

​
Introdução

Enterprise Os enriquecimentos Enterprise são metadados adicionais incluídos no corpo da resposta de algumas APIs de dados. Eles estão disponíveis apenas em planos de assinatura pagos. A tabela abaixo apresenta uma breve descrição de cada enriquecimento:
Enrichment:Descrição:
URLs expandidas e aprimoradasExpande automaticamente URLs encurtadas (por exemplo, bitly) incluídas no corpo de um Post e fornece metadados de título e descrição em HTML da página de destino.
Objeto de regras correspondentesIndica quais regras corresponderam aos Posts recebidos. O objeto retorna a tag da regra e o id da regra no objeto de resposta.
Metadados de enqueteIndica a presença de uma enquete em um Post, inclui a lista de opções da enquete e informa tanto a duração quanto o horário de expiração da enquete.
Geolocalização de perfilDados derivados da localização do perfil do usuário, incluindo as coordenadas [longitude, latitude] (quando possível) e metadados do local relacionados.

​
URLs Expandidas e Aprimoradas

O enriquecimento de URLs Expandidas e Aprimoradas expande automaticamente URLs encurtadas incluídas no corpo de um Post e inclui a URL resultante como metadata no payload. Além disso, esse enriquecimento também fornece metadata da página HTML a partir do title e description da página de destino. Detalhes importantes:
  • Para resolver um link encurtado, nosso sistema envia solicitações HTTP HEAD para a URL fornecida e segue os redirecionamentos até chegar à URL final. Essa URL final (NÃO o conteúdo da página em si) é então incluída no payload da resposta.
  • O enriquecimento de URL adiciona entre 5 e 10 segundos de latência a streams em tempo real
  • Para solicitações feitas à Full Archive Search API, os dados de enriquecimento de URL expandida estão disponíveis apenas para Posts com até 13 meses.
  • O enriquecimento de URL não está disponível para links de Post (incluindo Tweets com citação), links de Moments e links de perfil incluídos em um Post.   

​
Payload do Post

O enriquecimento de URL Expandida e Aprimorada pode ser encontrado dentro do objeto entities do payload do Post — especificamente no objeto entities.urls.unwound. Ele fornece os seguintes campos de metadata:
  • URL expandida - unwound.url
  • Status HTTP expandido - unwound.status
  • Título HTML da URL expandida - limite de 300 caracteres - unwound.title
  • Descrição HTML da URL expandida - limite de 1000 caracteres - unwound.description
Este é um exemplo de um objeto entities com o enriquecimento de URL: 
"entities": {
    "hashtags": [

    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/HkTkwFq8UT",
        "expanded_url": "http:\/\/bit.ly\/2wYTb9y",
        "display_url": "bit.ly\/2wYTb9y",
        "unwound": {
          "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/",
          "status": 200,
          "title": "11 Sites Para Aprender a Programar de Graça em 2017",
          "description": "É totalmente possível aprender a programar de graça...mas quais são os melhores recursos para isso? Aqui estão 11 sites onde você pode começar."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },
**Este é um exemplo de um objeto entities contendo um link de Post que não está enriquecido: ** 
"entities": {
  "urls": [{
    "url": "https://t.co/SywNbZdDmb",
    "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728",
    "display_url": "x.com/XDevelopers/s…",
     "indices": [
        142,
        165
     ]
   }
  ]
}

​
Operadores de filtragem

Os seguintes operadores filtram e fazem correspondência tokenizada nos fields relacionados aos metadata de URL: url:
  • Exemplo: “url:tennis”
  • Correspondência tokenizada em qualquer Expanded URL que inclua a palavra tennis
  • Também pode ser usado como filtro para incluir ou excluir links de um site específico usando algo como “url:npr.org”
url_title:
  • Exemplo: “url_title:tennis”
  • Correspondência tokenizada em qualquer título HTML da Expanded URL que inclua a palavra tennis
  • Faz correspondência com os dados do título HTML incluídos no payload, limitado a 300 caracteres.
url_description:
  • Exemplo: “url_description:tennis”
  • Correspondência tokenizada em qualquer descrição HTML da Expanded URL que inclua a palavra tennis
  • Faz correspondência com a descrição HTML incluída no payload, limitada a 1000 caracteres.  

​
Códigos de status HTTP

O enriquecimento de URL expandida também fornece o código de status HTTP da URL final que estamos tentando resolver. Em situações normais, será o valor 200. Outros valores da série 400 indicam problemas ao resolver a URL. Vários códigos de status podem ser retornados ao tentar resolver uma URL. Durante o processo de resolução, se houver um redirecionamento, iremos segui-lo indefinidamente até que:
  • Atinjamos um código da série 200 (sucesso)
  • Atinjamos um código de série que não seja de redirecionamento (falha)
  • Ocorra um timeout porque a URL final não pôde ser resolvida em um tempo razoável (retorna 408 — timeout)
  • Ocorra algum tipo de exceção  
Se ocorrer uma exceção, usamos o seguinte mapeamento entre motivos e códigos de status retornados:
MotivoCódigo de status retornado
Exceções de SSL403 (Forbidden)
Resolução não permitida pela URL405
Timeout de socket408 (Timeout)
Exceção de host desconhecido404 (Not Found)
Operação não suportada404 (Not Found)
Exceção de conexão404 (Not Found)
Argumento inválido400 (Bad Request)
Qualquer outro caso400 (Bad Request)

​
Regras de correspondência

O enriquecimento de regras de correspondência é um objeto de metadata que indica quais regras corresponderam aos Posts recebidos. Isso é mais comumente usado com o stream do PowerTrack. A correspondência é realizada por meio de correspondência exata dos termos contidos em uma regra, analisando o conteúdo da atividade com e sem pontuação. A correspondência não diferencia maiúsculas de minúsculas. Quando for identificado que o conteúdo contém todos os termos definidos na regra, haverá, no nível raiz, um objeto matching_rules indicando a(s) regra(s) que resultaram na correspondência. PowerTrack Posts entregues por meio do PowerTrack (tempo real, Replay e Histórico) conterão o objeto matching_rules da seguinte forma: 
"matching_rules": [{
        "tag": null,
        "id": 907728589029646336,
        "id_str": "907728589029646336"
    }]
No PowerTrack, o objeto matching_rules reflete todas as regras que correspondem ao resultado em questão. Em outras palavras, se mais de uma regra corresponder a um Post específico, ele será entregue apenas uma vez, mas o elemento matching_rules incluirá todas as regras que corresponderam.

​
Metadados de enquete

Os metadados de enquete são um enriquecimento gratuito disponível em todos os produtos (APIs Realtime e Historical) em cargas no formato nativo enriquecido. Eles indicam a presença de uma enquete em um Post, incluem a lista de opções da enquete e trazem tanto a duração quanto o horário de expiração. Esse enriquecimento facilita reconhecer a presença de uma enquete e permite a renderização correta de um Post com enquete para exibição.
Detalhes importantes:
  • Disponível em todas as APIs Enterprise (PowerTrack, Replay, Search, Historical PowerTrack)
    • Observação: Para Replay e Historical PowerTrack, esse metadata foi disponibilizado pela primeira vez em 22/02/2017.
  • Não inclui informações de voto nem resultados de enquete
  • Atualmente não há suporte a filtros/operadores
  • Disponível apenas em formato nativo enriquecido
    • O formato nativo enriquecido é uma configuração controlada pelo usuário que pode ser alterada a qualquer momento pelo Console: Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​
Payload de Post

O Post de enquete conterá a seguinte metadata no objeto “entities.polls” do payload:
  • Um array “options” com até quatro opções, incluindo a posição (1–4) e o texto da opção
  • Data de expiração da enquete
  • Duração da enquete
Consulte o payload de exemplo abaixo para mais detalhes.

​
Exemplo de Payload

Abaixo está um trecho do payload no formato nativo enriquecido que destaca a metadata de enquete adicionada: 
"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"A melhor resposta"
                   },
                   {
                      "position":2,
                      "text":"A melhor resposta"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

​
Geolocalização do perfil

​
Introdução

Muitos perfis de usuários do X incluem informações públicas de localização fornecidas pelo próprio usuário. Esses dados são retornados como uma string comum em user.location (consulte o dicionário de dados do objeto de usuário). O Profile Geo Enrichment adiciona geodados estruturados relevantes ao valor de user.location, geocodificando e normalizando as strings de localização quando possível. Tanto as coordenadas de latitude/longitude quanto os metadados de lugar relacionados são adicionados a user.derived.locations somente quando incluídos como parte do payload do Post em produtos de API Enterprise. Esses dados estão disponíveis ao usar o formato nativo enriquecido e podem ser filtrados com uma combinação de regras do PowerTrack.
Nota: Alguns dos geodados de suporte usados para criar o enriquecimento Profile Geo vêm de GeoNames.org e são usados pela X sob a Licença Creative Commons Attribution 3.0.
Os dados do Profile Geo serão incluídos nas APIs PowerTrack, Replay, Volume Stream, Search e Historical PowerTrack da X.

​
Dados geográficos de perfil

Enriched native field nameExample valueDescription
user.derived.locations.countryUnited StatesO país de origem do usuário que criou o Post.
user.derived.locations.country_codeUSUm código de país ISO-3166 de duas letras que corresponde ao país de origem do usuário que criou o Post.
user.derived.locations.localityBirminghamA localidade (geralmente a cidade) de origem do usuário que criou o Post.
user.derived.locations.regionAlabamaA região (geralmente estado/província) de origem do usuário que criou o Post.
user.derived.locations.sub_regionJefferson CountyA sub-região (geralmente condado) de origem do usuário que criou o Post.
user.derived.locations.full_nameBirmingham, Alabama, United StatesO nome completo (excluindo a sub-região) do local de origem do usuário que criou o Post.
User.derived.locations.geoSee BelowUm array que inclui um valor de latitude/longitude para uma coordenada que corresponde ao nível de granularidade mais baixo do local de origem do usuário que criou o Post.
As APIs Historical PowerTrack, Search e PowerTrack oferecem suporte à filtragem com base em dados geográficos de perfil. Consulte a documentação do produto apropriada para mais detalhes sobre quais operadores estão disponíveis para filtragem de dados geográficos de perfil.

​
Exemplo de payload

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "Estados Unidos",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Jefferson County",
                    "full_name": "Birmingham, Alabama, Estados Unidos",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

​
Limitações

  • O enriquecimento Profile Geo tenta determinar a melhor correspondência para o local geográfico descrito na string de localização do perfil. O resultado pode não ser preciso em todos os casos devido a fatores como múltiplos locais com nomes semelhantes ou nomes ambíguos.
  • Se não houver valor no campo de localização do perfil do usuário (actor.location), não tentaremos fazer uma classificação.
  • Nível de precisão: se um Profile Geo Enrichment só puder ser determinado com confiança nos níveis de país ou região, geografias de nível inferior, como subRegion e localidade, serão omitidas do payload.
  • O enriquecimento Profile Geo fornece coordenadas de latitude/longitude (um único ponto) que correspondem ao nível de precisão dos resultados do enriquecimento. Essas coordenadas representam o centro geográfico dos resultados de localização do enriquecimento. Por exemplo, se o nível de precisão for País, essas coordenadas serão definidas para o centro geográfico desse país.
  • Os operadores PowerTrack fornecidos para propriedades de endereço (locality/region/country/country code) são intencionalmente granulares para permitir muitas combinações de regras. Ao tentar segmentar um local específico que compartilha nome com outro, considere combinar regras de endereço. Por exemplo, o seguinte evitaria correspondências para “San Francisco, Philippines”: profile_locality:“San Francisco” profile_region:California. Ao criar regras que segmentam campos individuais de Profile Geo, lembre-se de que cada aumento no nível de granularidade limitará os resultados que você verá. Em alguns casos, ao analisar dados de uma cidade, talvez você prefira depender apenas de uma regra de região quando a região tiver sobreposição significativa com a cidade; por exemplo, a cidade de Zurique, Suíça, pode ser efetivamente segmentada junto com áreas ao redor com profile_region:“Zurich”.
  • Uso com Posts com geolocalização nativa: o enriquecimento Profile Geo fornece um tipo alternativo de geografia para um Post, diferente do valor de geolocalização nativo no payload. Esses dois tipos de geografia podem ser combinados para capturar todos os Posts possíveis relacionados a uma determinada área (com base nos geodados disponíveis), embora não sejam conceitualmente equivalentes.
⌘I