Informações gerais

Autenticação

Todas as solicitações de API exigem uma chave de API. Para recuperar a chave, faça login em sua conta e vá para Developer Tools > API Keys. Você pode inserir a chave no parâmetro api_key em sua solicitação ou fornecer o token em um cabeçalho HTTP de autorização.

Limites de taxa

Os limites padrão para a API da Singular são:

• Relatórios assíncronos: até 100 relatórios assíncronos em execução simultânea.
• Relatórios síncronos: até 3 relatórios síncronos em execução simultânea.
• Limite de linhas de relatório único: até 200 mil linhas por consulta.
• Limite global diário de linhas: até 3 milhões de linhas em um único dia (compartilhado entre todas as suas consultas).

A Singular se reserva o direito de ajustar o limite de taxa para determinados endpoints a fim de continuar e fornecer um serviço de alta qualidade a todos os nossos clientes. Entre em contato conosco se houver uma necessidade específica de exceder a limitação padrão.

Lista de pontos de extremidade da API de relatórios

Os seguintes endpoints de API estão disponíveis:

Criar ponto de extremidade de relatório assíncrono

import requests
  url = "https://api.singular.net/api/v2.0/create_async_report"
  query_params = {"api_key": "<API KEY>"}
  payload = {
    "dimensions":"app,source,os,country_field",
    "metrics": "custom_impressions,custom_clicks,custom_installs",
    "start_date":"2020-01-01",
    "end_date": "2020-01-01",
    "time_breakdown": "all",
    "format": "csv",
    "country_code_format": "iso"
  }
  response = requests.post(url=url, params=query_params, data=payload)
  print(response.text)

{
      "status": 0,
      "substatus": 0,
      "value": {
          "report_id": "5cfdb747dd464cd09a9c463e5be9691f"
      }
  }

Dimensões e métricas disponíveis

Consulte o Glossário de métricas e dimensões para obter uma descrição de cada campo.

Dados de rede

Dadosdo rastreador

Dados combinados

Ponto final de disponibilidade de dados

Uso

Esse ponto de extremidade retorna se, em um determinado dia, os dados estão disponíveis para cada uma de suas fontes ou conectores de dados.

Recomendamos usar esse endpoint para verificar se os dados já estão disponíveis para ontem antes de executar seus relatórios diários.

Exemplo de consulta (Python)

import requests

  url = "https://api.singular.net/api/v2.0/data_availability_status"
  queryparams = {
    "api_key":"<API_KEY>",
    "expanded":"true",
    "format": "json",
    "data_date":"2021-02-01",
    "display_non_active_sources":"true"
  }
  
  response = requests.get(url=url, params=queryparams)

Parâmetros da consulta

Exemplo de saída (quando expandido=verdadeiro)

{
      "status": 0, 
      "substatus": 0, 
      "value": {
          "is_all_data_available": false,
          "data_connectors": [{
              "data_connector_id": "dgd7934875", 
              "data_connector_source_name": "Vungle", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": true, 
              "is_empty_data": false, 
              "last_updated_utc": "2021-02-08T10:10:07", 
              "data_connector_timestamp_utc": "2021-02-08T10:10:07", 
              "status": "data populated"
          }, {
              "data_connector_id": "youi293478", 
              "data_connector_source_name": "IronSource", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": false, 
              "is_empty_data": "N/A", 
              "last_updated_utc": "N/A", 
              "data_connector_timestamp_utc": "N/A", 
              "status": "data not populated"
          }]
      }
  }

Parâmetros de saída

{'is_all_data available': false,
  'data_sources': [
  {'username': u'facebook@singular.net',
   'status': 'data populated',
   'is_empty_data': false,
   'is_active_last_30_days': true,
   'last_updated_utc': '2018-05-03T10:12:18'
   'source': u'Facebook',
   'is_available': true},
   {'username': u'vungle@singular.net',
   'status': 'data populated',
   'is_empty_data': true,
   'is_active_last_30_days': true,
   'last_updated_utc': '2018-05-03T10:12:18'
   'source': u'Vungle',
   'is_available': true},
   {'username': u'applovin@singular.net',
   'status': 'data not populated',
   'is_empty_data': N/A,
   'is_active_last_30_days': true,
   'last_updated_utc': N/A
   'source': u'Applovin',
   'is_available': false}
  ]}

Ponto de extremidade Get Report Status

Uso

Esse ponto de extremidade retorna o status de um determinado relatório que foi gerado usando o ponto de extremidade Create Async Report. Se o relatório tiver terminado de ser executado, o ponto de extremidade também retornará um URL de download.

Se o relatório falhar, o ponto de extremidade retornará uma mensagem de erro que você poderá usar para solucionar o problema (consulte a tabela Códigos de erroe o guia Perguntas frequentes e solução de problemas da API).

Para saber mais, consulte a seção Processo de consultano Guia da API do Singular Reporting.

Importante:

• Às vezes, os relatórios podem levar até alguns minutos para serem concluídos.
• Não consulte o endpoint de status do relatório mais de uma vez a cada 10 segundos por relatório.
• Defina um tempo limite. Em alguns casos raros, um relatório pode ficar preso no status "Queued" (Enfileirado) ou "Started" (Iniciado). Se o status não for "Done" (Concluído) ou "Failed" (Falha) após 30 minutos, recomendamos enviar o relatório novamente (o que lhe dará um novo ID de relatório para consulta).

Exemplo de consulta

import requests
  url = "https://api.singular.net/api/v2.0/get_report_status"
  querystring = {
    "report_id":"5cfdb747dd45be9691f",
    "api_key": "<API KEY>"
  }
  response = requests.get(url=url, params=querystring)
  print(response.text)

Parâmetros da consulta

Saída de amostra

{
    "status": 0,
    "substatus": 0,
    "value": {
        "status": "DONE",
        "url_expires_in": 3600,
        "generated_url_time_in_utc": "2018-05-13T08:26:18.457690+00:00",
        "url_expired_time_in_utc": "2018-05-13T09:26:18.457690+00:00",
        "download_url": "https://singular-reports-results.s3.amazonaws.com/singular/xxxxxxxxx",
        "report_id": "5cfdb747dd45be9691f"
    }
  }

Parâmetros de saída

Ponto de extremidade dos filtros

Uso

Use esse ponto de extremidade auxiliar para recuperar uma lista atualizada das dimensões pelas quais você pode filtrar seu relatório e os valores possíveis para cada dimensão.

Exemplo de consulta

import requests
  url = "https://api.singular.net/api/v2.0/reporting/filters"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

Parâmetros da consulta

Saída de amostra

{
    "status": 0,
    "substatus": 0,
    "value": {
      "dimensions": [
        {
          "name": "os",
          "display_name": "OS",
          "values": [
              {"name": 4, "display_name": "Android"},
              {"name": 1, "display_name": "iOS"}
            ],
        },
        {
          "name": "source",
          "display_name": "Source",
          "values": [{"name": "adwords", "display_name": "AdWords"}]
        }
      ]
    }
  }

Ponto de extremidade de dimensões personalizadas

Uso

Use esse ponto de extremidade para recuperar os IDs de quaisquer dimensões personalizadas configuradas para sua conta. Em seguida, você pode usar os IDs das dimensões personalizadas ao consultar o ponto de extremidade Criar relatório assíncrono (em vez de ou além de qualquer uma das dimensões padrão).

Para saber mais sobre dimensões personalizadas e como criá-las, consulte as Perguntas frequentes sobre dimensões personalizadas.

Exemplo de consulta

import requests
  url = "https://api.singular.net/api/custom_dimensions"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

Parâmetros da consulta

Saída de amostra

{
    "status": 0,
    "substatus": 0,
    "value": {
      "custom_dimensions": [
        {"display_name": "Channel Type", "id": "e471cb6b83684532e5e83cd"},
        {"display_name": "Region", "id": "1dcfdb1ad861fba4b098e2"}
      ]
    }
  }

Ponto de extremidade de métricas de coorte

Uso

Use esse endpoint para recuperar todas as métricas de coorte e períodos de coorte disponíveis para sua conta. Isso inclui todos os eventos in-app que você configurou para serem rastreados pelo Singular (consulte as Perguntas frequentes sobre eventos). Em seguida, você pode especificar essas métricas e períodos ao executar uma consulta no ponto de extremidade Criar relatório assíncrono.

Observe que na consulta Criar relatório assíncrono você precisa usar o "nome" da métrica, não o "nome de exibição".

Exemplo de consulta

import requests
  url = "https://api.singular.net/api/cohort_metrics"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

Parâmetros da consulta

Saída de amostra

{
      "status": 0,
      "substatus": 0,
      "value": {
          "metrics": [
              {"display_name": "ROI","name": "roi"},
              {"display_name": "Revenue","name": "revenue"}
          ],
          "periods": ["1d","3d","5d","7d","14d","30d","actual"]
      }
  }

Parâmetros de saída

Ponto de extremidade de métricas de conversão

Uso

Use esse ponto de extremidade para recuperar todos os eventos de conversão disponíveis para sua conta. Em seguida, você pode especificar esses eventos como métricas ao executar uma consulta no ponto de extremidade Criar relatório assíncrono.

Observe que na consulta Criar relatório assíncrono você precisa usar o "nome" da métrica, não o "nome de exibição".

Exemplo de consulta

import requests
  url = "https://api.singular.net/api/conversion_metrics"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

Parâmetros da consulta

Saída de amostra

{
    "status": 0, 
    "substatus": 0, 
    "value": {
      "metrics": [
        {"display_name": "5-second video view", "name": "87dfg34453hsfg6f"}, 
        {"display_name": "5-second video view CPE", "name": "87dfg34453hsfg6fCPE"},   
        {"display_name": "Sign up", "name": "iuq353fidr76w846fha"}, 
        {"display_name": "Sign up CPE", "name": "iuq353fidr76w846fhaCPE"}, 
        {"display_name": "Post engagement", "name": "b59cje9fcgw0th"}, 
        {"display_name": "Post engagement CPE", "name": "b59cje9fcgw0thCPE"},
      ]
    }
  }

Parâmetros de saída

Códigos de erro

A Singular usa códigos de resposta HTTP padrão para indicar o sucesso ou a falha de uma solicitação de API. Em geral, os códigos 200 correspondem a sucesso, os códigos no intervalo 4xx indicam um erro que falhou com base nas informações fornecidas (por exemplo, um parâmetro obrigatório foi omitido) e os códigos 5xx são para outros problemas.

Consulte também: Perguntas frequentes e solução de problemas da API de relatórios