Primeiros passos

Crie sua conta, adicione uma forma de pagamento, obtenha sua chave de API e faça sua primeira chamada à Listings API.

Este guia explica como criar uma conta, obter sua primeira chave de API e fazer uma requisição à Listings API.

Passe diário do sandbox

Quando um passe diário do sandbox estiver disponível, você poderá se cadastrar com seu nome, e-mail e empresa, sem cartão nem senha, e usar a mesma API e o mesmo servidor MCP por 24 horas. Enviamos a você um link e um código de 6 dígitos por e-mail. Sua conta só é criada e suas 24 horas só começam quando você abre o link e clica em Start my day pass (Iniciar meu passe diário), ou quando o código é usado, de modo que um agente de IA pode iniciar o passe para você usando o código. Uma conta sandbox comporta até 2 locais, abrange os endpoints de locais e listagens e sincroniza suas listagens apenas com diretórios de demonstração listingsAPI, nunca com plataformas de publicação reais. Quando as 24 horas terminam, as chaves de API da conta param de funcionar, e você tem 48 horas para contratar o Launch ou o Growth com o mesmo e-mail antes que a conta sandbox e seus dados sejam excluídos. O passe diário não tem senha, portanto, para entrar novamente, escolha Email me a sign-in link (Enviar um link de login por e-mail) na página de login. O guia do passe diário contém todos os detalhes, incluindo as chamadas que um agente faz.

1. Crie sua conta

Escolha um plano na página de preços para abrir o formulário de cadastro e, em seguida, informe seu first name (nome), last name (sobrenome), work email (e-mail corporativo) e company (empresa). Você já tem uma conta? Faça login.

2. Adicione uma forma de pagamento

Depois que você enviar o formulário, redirecionaremos você ao nosso provedor de pagamentos para adicionar um cartão. Seu teste gratuito começa imediatamente e se converte no plano que você escolheu quando o teste termina, portanto cancele antes disso se não quiser receber uma cobrança. As perguntas frequentes sobre preços informam a duração atual do teste e os limites dos planos.

Após a conclusão do checkout, enviamos a você um link por e-mail para definir sua senha e ativar sua conta. Depois de definir sua senha, faça login com seu e-mail e senha ou escolha Email me a sign-in link (Enviar um link de login por e-mail) para receber um link mágico de uso único.

4. Obtenha sua chave de API

Sua primeira chave de API é emitida automaticamente quando sua conta é criada; você pode encontrá-la no painel, em API Keys. Para criar outra, escolha New key (Nova chave), dê um nome a ela e selecione seu nível de acesso (Read (Leitura) ou Write (Escrita)).

5. Faça sua primeira requisição

Autentique cada requisição com um cabeçalho Authorization cujo valor seja a string literal API (observe o espaço no final), seguida da sua chave:

Shell

curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

A resposta tem uma estrutura aninhada, em vez de ser apenas um array: os resultados ficam em data.allLocations, cada registro é um edges[].node e pageInfo contém o cursor de paginação e os totais.

JSON

{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

Para avançar para a próxima página, envie de volta pageInfo.endCursor como ?after=… enquanto pageInfo.hasNextPage for true e também pare se uma página retornar com um array edges vazio. Cada edge também contém seu próprio cursor, e o cursor do último edge é o endCursor dessa página, portanto qualquer um dos valores funciona como ?after=.

Nem todos os endpoints de lista usam a mesma paginação

A estrutura edges / node / pageInfo acima segue o estilo de cursor Relay, que é apenas um de três:

Paginação por cursor (first, after → edges[].node mais pageInfo com endCursor / hasNextPage): locais, busca de locais e os endpoints de avaliações (interações por local e a consolidação da conta).
Paginação por offset (page, perPage → um array records mais pageInfo com totalRecords, totalPages, hasNextPage, hasPreviousPage): contas conectadas, sugestões de conexão, publicações de um local, publicações em massa de um local e a consolidação de listagens duplicadas de toda a conta.
Arrays simples, sem nenhuma paginação: os endpoints de catálogo (subcategorias, países e estados, sites do plano) e as fotos de um local.

Confira o exemplo de resposta na própria página do endpoint antes de escrever um loop de paginação; um loop de cursor usado com um endpoint de offset lê uma chave edges que nunca está presente.

Próximas etapas

Passe diário do sandbox: experimente locais e listagens sem precisar de cartão. Você ou seu agente de IA pode ativá-lo.
Autenticação: cabeçalhos de chave de API e rotação de chaves.
Códigos de erro: códigos de status HTTP e a estrutura da resposta de erro.
SDKs: clientes tipados para Python e Node.