Consulta países, estados y categorías

Consulta países y códigos de estado admitidos, el id numérico de categoría y las plataformas de publicación de tu plan antes de crear una ubicación.

Para crear una ubicación se necesitan tres valores que deben proceder de la API: un countryIso y un stateIso que la API acepte, un subCategoryId numérico y, si quieres limitar las plataformas de publicación, los ids de los sitios de tu plan. Tres endpoints de catálogo los proporcionan. Los tres devuelven un array simple sin paginación.

1. Enumera los países y códigos de estado

GET /countries devuelve todos los países admitidos con su código ISO, un indicador hasCity y un array states. Los valores de iso se usan en countryIso y stateIso al crear y actualizar. El Python SDK expone esta operación como client.countries() y el 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 es obligatorio al crear; con false, se descarta cualquier ciudad que envíes. stateRequired: true significa que stateIso es obligatorio y debe ser uno de los states del país; con false, omítelo. hasPostalCode: true significa que el país utiliza códigos postales, así que envía postalCode con la dirección. El endpoint de países explica cada indicador.

2. Busca el id de una categoría

GET /sub-categories devuelve el catálogo completo de categorías. El valor que envías como subCategoryId es databaseId, el entero, no el id en base64. Restaurantes, por ejemplo, es 1432. Filtra la lista por nombre en tu propio código; no hay ningún parámetro de búsqueda en el 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 qué se usa
`databaseId`	El entero que debes enviar como `subCategoryId`, o dentro de `additionalCategoryIds` para un máximo de 9 categorías secundarias.
`name`	La etiqueta legible que se muestra en un selector y se utiliza para buscar coincidencias.
`key`	Un slug del nombre apto para URL que se mantiene estable aunque cambie el nombre.
`primary`	Indica si la categoría puede ser la subcategoría principal de una ubicación. Selecciona únicamente entradas `true` para `subCategoryId`.

3. Consulta qué plataformas de publicación cubre tu plan

GET /plan-sites enumera todas las plataformas de publicación de tu plan con un id numérico, un url, los países que acepta cada una y los países en los que respeta hideAddress. Estos ids son los únicos valores válidos para enabledSiteIds al crear y submissionDisabledSiteIds al actualizar. Filtra por el país de la ubicación para ofrecer únicamente plataformas de publicación que la acepten.

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"]      }    ]  }}

Ambos arrays de países están truncados aquí; la respuesta real puede incluir 50 códigos o más por sitio. Para un negocio con área de servicio, comprueba también hideAddressSupportedCountries, ya que una plataforma de publicación que acepte el país puede rechazar una ficha sin dirección física.

4. Almacena estas consultas en caché

Los tres catálogos cambian con poca frecuencia y ninguno utiliza paginación, así que obtén cada uno una vez al iniciar, guárdalo en memoria o en una tabla pequeña y actualízalo periódicamente. Consultarlos durante cada operación de creación consume tu límite de solicitudes sin devolver datos nuevos; en el plan Launch, eso supone 3 de tus 10 solicitudes por minuto.

Catálogo	Tamaño	Cuándo actualizar
Países	Decenas de países, cientos de estados	Con poca frecuencia. Una vez al día es más que suficiente.
Subcategorías	Aproximadamente 6,000 entradas	A diario, o cuando una operación de creación falle por un `subCategoryId` desconocido.
Sitios del plan	Decenas de plataformas de publicación	Cuando cambie el plan, ya que la lista está limitada a tu plan.

Crea un mapa de name en minúsculas a databaseId para las subcategorías y un mapa de countryIso a states para los países. Valida la dirección con los datos de la caché antes de llamar a la operación de creación, para que tu aplicación detecte un countryIso no admitido (SY10036) o la ausencia de city (SY10126) antes de enviar la solicitud.

Próximos pasos

Añade una ubicación: usa subCategoryId, countryIso y los identificadores de sitio que acabas de consultar.
Actualiza una ubicación: cambia las categorías o excluye plataformas de publicación con submissionDisabledSiteIds.
Enumera los países y estados admitidos, Enumera las subcategorías y Enumera los sitios del plan: las páginas de referencia.