Listings APIListings API
Iniciar sesión

Publicaciones

Publica anuncios, eventos y ofertas en Google y Facebook mediante client.posts.

Todos los métodos de publicaciones se encuentran en client.posts. Los métodos que reciben un location_id aceptan IDs numéricos o codificados en base64; consulta IDs de ubicación.

Las publicaciones se publican en dos sitios: GOOGLE y FACEBOOK. Los tipos de publicación son ANNOUNCEMENT, EVENT, OFFER, COVID19 y PRODUCT. Los tipos de llamada a la acción son BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP y GET_OFFER; cta_type y cta_url siempre deben proporcionarse juntos.

Publicación asíncrona

La publicación es asíncrona. Las llamadas de creación devuelven status: INPROGRESS; consulta periódicamente posts.retrieve() (o posts.bulk_retrieve() para campañas masivas) hasta que el estado sea SUCCESS y comprueba publishDetails[].submissionError para detectar fallos por sitio.

Mensajes por sitio

Todos los métodos de creación aceptan message como una cadena de texto simple, que publica el mismo texto en todos los sitios, o como un dict que asigna un texto a cada sitio:

Python
message = {  "GOOGLE": "Book your summer checkup today!",  "FACEBOOK": "Summer checkups are here. Tag a friend who needs one!",}

Cuando message es un dict, debe contener una entrada para cada sitio de sites; si falta alguna, el SDK lanza ValidationError antes de realizar cualquier llamada de red.

posts.bulk_publish

Publica una misma publicación en varias ubicaciones de Google y Facebook con una sola llamada. Esta es la forma recomendada de publicar: sites incluye ambos de forma predeterminada, el mensaje único (o el dict por sitio) se convierte en una entrada por sitio, los IDs de ubicación se codifican automáticamente y los datos que se van a enviar se validan en el cliente antes de realizar cualquier llamada de red.

Python
client.posts.bulk_publish(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    post_type: str = "ANNOUNCEMENT",    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    context_info: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
ArgumentoTipoDescripción
namestrNombre interno de la campaña (no se muestra a los clientes). Obligatorio.
location_idslist[str | int]Todas las ubicaciones en las que publicar (IDs numéricos o en base64). Obligatorio.
messagestr | dictCuerpo de la publicación para todos los sitios, o un dict por sitio. Obligatorio.
siteslist[str]Sitios de destino. El valor predeterminado es ["GOOGLE", "FACEBOOK"].
post_typestrANNOUNCEMENT (predeterminado), EVENT, OFFER, COVID19 o PRODUCT.
cta_typestrBotón opcional de llamada a la acción; requiere cta_url.
cta_urlstrDestino del botón de llamada a la acción.
media_urlstrURL pública opcional de una imagen que se adjunta en todos los sitios.
scheduled_datesdictIntervalo opcional de {"startDatetime", "endDatetime"}.
context_infodictDetalles del evento o de la oferta cuando post_type los requiere.
additional_fieldsdictCampos adicionales de camelCase sin anidar que se incorporan tal cual.
Python
result = client.posts.bulk_publish(  name="Holiday hours",  location_ids=[16808, 16809, 16810],  message="Open until 10pm through the holidays!",  media_url="https://cdn.example.com/holiday.jpg",  cta_type="LEARN_MORE",  cta_url="https://example.com/holiday-hours",)print(result.socialPost.id, result.socialPost.status)  # INPROGRESS, publishes async

posts.create_announcement

Crea una publicación de tipo ANNOUNCEMENT: un mensaje simple con una llamada a la acción y contenido multimedia opcionales. El valor predeterminado de sites es ["GOOGLE"].

Python
client.posts.create_announcement(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_announcement(  name="Grand Opening",  location_ids=[16808],  message="Acme Dental is now open!",  sites=["GOOGLE"],  cta_type="LEARN_MORE",  cta_url="https://acmedental.example.com/opening",)print(result.socialPost.id)

posts.create_event

Crea una publicación de tipo EVENT con un título y un intervalo de inicio y fin. Google exige el título del evento; el SDK lanza ValidationError si falta. start_day y end_day son fechas (YYYY-MM-DD); start_time y end_time son cadenas de texto para mostrar, como "10:00am".

Python
client.posts.create_event(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    start_day: str,    end_day: str,    start_time: str | None = None,    end_time: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_event(  name="Free checkup day",  location_ids=[16808],  message="Join us for free dental checkups!",  title="Free Checkup Day",  start_day="2026-08-01",  end_day="2026-08-01",  start_time="10:00am",  end_time="4:00pm",  cta_type="BOOK",  cta_url="https://acmedental.example.com/book",)print(result.socialPost.id)

posts.create_offer

Crea una publicación de tipo OFFER con un cupón, un descuento y las condiciones. title da nombre a la oferta y es obligatorio; start_day y end_day (YYYY-MM-DD) delimitan su vigencia.

Python
client.posts.create_offer(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    coupon_code: str | None = None,    discount: str | None = None,    redeem_url: str | None = None,    terms_conditions: str | None = None,    start_day: str | None = None,    end_day: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_offer(  name="Summer whitening sale",  location_ids=[16808],  message="20% off teeth whitening all week!",  title="Summer Whitening Sale",  coupon_code="SUMMER20",  discount="20%",  redeem_url="https://acmedental.example.com/sale",  terms_conditions="One per patient. Not valid with other offers.",  start_day="2026-08-01",  end_day="2026-08-07",)print(result.socialPost.id)

posts.create

Crea una publicación a partir de un dict con el cuerpo sin procesar. Pasas los campos sin anidar en camelCase y la función auxiliar los incluye en el objeto input que exige la API antes de enviarlos: el cuerpo transmitido es {"input": {...}}, nunca un cuerpo sin anidar. locationIds ya debe estar codificado en base64. Da preferencia a los métodos de creación tipados anteriores para usar argumentos con nombre, codificación automática de IDs y validación en el cliente.

Python
client.posts.create(body: dict) -> APIObject

Obligatorios: postName, locationIds (base64), postType, postSites.

Python
result = client.posts.create({  "postName": "Grand Opening",  "locationIds": ["TG9jYXRpb246MTY4MDg="],  "postType": "ANNOUNCEMENT",  "postSites": ["GOOGLE"],  "postMessage": [{"site": "GOOGLE", "message": "We are now open!"}],})print(result.socialPost.id)

posts.retrieve

Obtén una publicación con su contenido, el estado de publicación por sitio y los datos analíticos. Consulta este método periódicamente después de una creación hasta que status sea SUCCESS.

Python
client.posts.retrieve(post_id: str) -> APIObject
Python
post = client.posts.retrieve("U29jaWFsUG9zdDo0NDEyMg==")print(post.status)for detail in post.publishDetails:  print(detail.site, detail.submissionError)

posts.delete

Elimina una publicación y retírala de todos los sitios en los que se publicó.

Python
client.posts.delete(post_id: str) -> APIObject
Python
client.posts.delete("U29jaWFsUG9zdDo0NDEyMg==")

posts.list_for_location

Enumera las campañas de publicaciones dirigidas a una ubicación. La paginación se basa en el desplazamiento: el resultado contiene .records y .pageInfo con totalPages, totalRecords y hasNextPage. La respuesta se encuentra en postsByLocation.

Esta ruta rechaza un tag, por lo que, desde la versión 0.5.3, el SDK acepta el argumento por compatibilidad con versiones anteriores y nunca lo incluye en la solicitud enviada. Usa posts.bulk_list_for_location cuando necesites filtrar por etiquetas.

Python
client.posts.list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject
Python
result = client.posts.list_for_location(16808, page=1, per_page=10)for post in result.records:  print(post.id, post.name)print(result.pageInfo.totalRecords)

posts.bulk_retrieve

Obtén una campaña masiva (para varias ubicaciones) con el estado de publicación y los datos analíticos por ubicación.

Python
client.posts.bulk_retrieve(bulk_post_id: str) -> APIObject
Python
bulk = client.posts.bulk_retrieve("QnVsa1Bvc3Q6OTk=")print(bulk.status)

posts.bulk_list_for_location

Enumera las campañas masivas (para varias ubicaciones) que incluyen una ubicación. Los parámetros y la estructura del resultado son los mismos que los de posts.list_for_location.

Python
client.posts.bulk_list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject
Python
result = client.posts.bulk_list_for_location(16808, page=1, per_page=10)for campaign in result.records:  print(campaign.id, campaign.name)

Consulta también

  • Ubicaciones: crea y gestiona las ubicaciones en las que publicas
  • Fichas: consulta el estado de sincronización por ubicación
  • Analítica: analítica de perfiles de Google, Bing y Facebook