Consulte países, estados e categorias

Consulte países e códigos de estado aceitos, o ID numérico da categoria de negócio e as plataformas de publicação do seu plano antes de criar um local.

A criação de um local exige três valores que devem vir da API: um countryIso e um stateIso aceitos pela API, um subCategoryId numérico e, se você quiser limitar as plataformas de publicação, os ids dos sites do seu plano. Três endpoints de catálogo fornecem esses valores. Os três retornam um array simples, sem paginação.

1. Liste países e códigos de estado

GET /countries retorna todos os países compatíveis com seus respectivos códigos ISO, um indicador hasCity e um array states. Os valores de iso preenchem countryIso e stateIso na criação e na atualização. O Python SDK disponibiliza essa operação como client.countries() e o Node SDK como client.fetchCountries().

Countries

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

JSON

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

hasCity: true significa que city é obrigatório na criação; com false, a cidade que você enviar será descartada. stateRequired: true significa que stateIso é obrigatório e deve ser um dos states do país; com false, omita esse campo. hasPostalCode: true significa que o país usa códigos postais, então envie postalCode com o endereço. O endpoint de países explica cada indicador.

2. Encontre o id de uma categoria

GET /sub-categories retorna o catálogo completo de categorias. O valor que você envia como subCategoryId é databaseId, o número inteiro, e não o id em base64. Restaurantes, por exemplo, corresponde a 1432. Filtre a lista por nome no seu próprio código; não há parâmetro de busca no servidor.

Find a category

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'

JSON

{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}

Campo	Para que usar
`databaseId`	O número inteiro a enviar como `subCategoryId` ou dentro de `additionalCategoryIds` para até 9 categorias secundárias.
`name`	O rótulo legível para exibir em um seletor e usar na busca por correspondências.
`key`	Um slug do nome adequado para URLs, que permanece estável quando o nome muda.
`primary`	Indica se a categoria pode ser a subcategoria principal de um local. Selecione apenas entradas `true` para `subCategoryId`.

3. Veja quais plataformas de publicação seu plano inclui

GET /plan-sites lista todas as plataformas de publicação do seu plano com um id numérico, um url, os países que cada uma aceita e os países onde cada uma respeita hideAddress. Esses ids são os únicos valores válidos para enabledSiteIds na criação e submissionDisabledSiteIds na atualização. Filtre pelo país do local para oferecer apenas plataformas de publicação que o aceitem.

Plan sites

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'

JSON

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

Os dois arrays de países estão truncados aqui; a resposta real pode listar 50 ou mais códigos por site. Para uma empresa que atende em uma área de serviço, verifique também hideAddressSupportedCountries, pois uma plataforma de publicação que aceita o país ainda pode recusar uma listagem sem endereço físico.

4. Armazene essas consultas em cache

Os três catálogos mudam raramente e nenhum deles usa paginação, então busque cada um uma vez na inicialização, mantenha os dados na memória ou em uma pequena tabela e atualize-os periodicamente. Chamá-los diretamente a cada criação consome seu limite de requisições sem retornar dados novos; no plano Launch, isso equivale a 3 das suas 10 requisições por minuto.

Catálogo	Tamanho	Quando atualizar
Países	Dezenas de países, centenas de estados	Raramente. Uma vez por dia é mais do que suficiente.
Subcategorias	Cerca de 6.000 entradas	Diariamente ou quando uma criação falhar devido a um `subCategoryId` desconhecido.
Sites do plano	Dezenas de plataformas de publicação	Quando houver uma mudança de plano, pois a lista é restrita ao seu plano.

Crie um mapeamento de name em letras minúsculas para databaseId para as subcategorias e um mapeamento de countryIso para states para os países. Valide o endereço com base no cache antes de fazer a chamada de criação, para que um countryIso não compatível (SY10036) ou a ausência de city (SY10126) seja detectado na sua aplicação antes do envio da requisição.

Próximos passos

Adicione um local: use subCategoryId, countryIso e os IDs de sites que você acabou de consultar.
Atualize um local: altere categorias ou exclua plataformas de publicação com submissionDisabledSiteIds.
Liste os países e estados compatíveis, Liste as subcategorias e Liste os sites do plano: as páginas de referência.