Listings APIListings API
Entrar

Início rápido

Conecte-se à Listings API, liste seus locais, crie um local com uma única chamada e responda a uma avaliação.

1. Configure sua chave de API

Obtenha sua chave em API Keys → New key no painel de desenvolvedor da Listings API. O SDK lê a chave automaticamente da variável de ambiente LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Liste seus locais

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

Saída esperada:

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

Para solicitar todas as páginas automaticamente, use client.locations.list(first=100).auto_paging_iter(); ele percorre as páginas usando cursores, para que você não precise gerenciá-los manualmente.

3. Crie um local em uma única chamada

locations.add() recebe cada campo obrigatório como um argumento nomeado e valida esses campos no cliente (comprimento do nome, descrição com no mínimo 200 caracteres, categoria, país, cidade) antes de qualquer chamada de rede, para que um payload inválido resulte imediatamente em um erro claro do tipo ValidationError.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

As plataformas de publicação usam a descrição como texto principal da listagem, por isso a API exige pelo menos 200 caracteres. Obtenha valores válidos de sub_category_id em client.subcategories().

O novo ID é retornado como uma string em base64, como TG9jYXRpb246MTY4MDg=. IDs numéricos e em base64 são intercambiáveis em todos os pontos em que o SDK aceita um ID de local, portanto client.locations.retrieve(16808) e client.locations.retrieve("TG9jYXRpb246MTY4MDg=") buscam o mesmo local.

4. Responda a uma avaliação

Liste as avaliações de um local e responda usando o interactionId da avaliação:

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

Verifique canRespond antes de responder e nunca acesse um elemento de uma página por índice sem antes verificar se ela não está vazia: reviews[0] em uma página vazia gera IndexError, e responder a uma avaliação que a plataforma de origem encerrou causa uma falha na plataforma de publicação, e não na API.

Se a plataforma rejeitar a resposta, o SDK gera ValidationError mesmo quando o status HTTP é 200; você nunca precisa verificar os indicadores success por conta própria.

5. Trate os erros

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

Chaves inválidas resultam em HTTP 401 com o código de plataforma SY90005; o SDK gera AuthenticationError. Por precaução, ele também trata o mesmo código de erro se ele vier no corpo de uma resposta 200. Consulte Tratamento de erros para ver a hierarquia completa de exceções e a referência de códigos de erro para ver a matriz de status HTTP.

Próximos passos