Listings APIListings API
Masuk

Postingan

Publikasikan pengumuman, acara, dan penawaran ke Google dan Facebook melalui client.posts.

Semua metode postingan berada di client.posts. Metode yang menerima location_id menerima ID numerik atau ID yang dienkode dalam base64; lihat ID Lokasi.

Postingan dipublikasikan ke dua situs: GOOGLE dan FACEBOOK. Jenis postingan adalah ANNOUNCEMENT, EVENT, OFFER, COVID19, dan PRODUCT. Jenis ajakan bertindak adalah BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, dan GET_OFFER; cta_type dan cta_url harus selalu diberikan bersama.

Publikasi asinkron

Publikasi berlangsung secara asinkron. Pemanggilan pembuatan mengembalikan status: INPROGRESS; periksa posts.retrieve() secara berkala (atau posts.bulk_retrieve() untuk kampanye massal) hingga statusnya menjadi SUCCESS, dan periksa publishDetails[].submissionError untuk mengetahui kegagalan per situs.

Pesan per situs

Setiap metode pembuatan menerima message sebagai string biasa, yang memublikasikan teks yang sama ke setiap situs, atau dict yang memetakan situs ke teks:

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

Jika message berupa dict, dict tersebut harus berisi entri untuk setiap situs dalam sites; SDK memunculkan ValidationError sebelum melakukan pemanggilan jaringan apa pun jika ada entri yang tidak disertakan.

posts.bulk_publish

Publikasikan satu postingan untuk banyak lokasi di Google dan Facebook dalam satu pemanggilan. Ini adalah cara yang disarankan untuk memublikasikan postingan: secara bawaan, sites mencakup keduanya, satu pesan (atau dict per situs) dikembangkan menjadi satu entri per situs, ID lokasi dienkode secara otomatis, dan payload divalidasi di sisi klien sebelum pemanggilan jaringan apa pun.

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
ArgumenTipeDeskripsi
namestrNama kampanye internal (tidak ditampilkan kepada pelanggan). Wajib diisi.
location_idslist[str | int]Semua lokasi tujuan publikasi (ID numerik atau base64). Wajib diisi.
messagestr | dictIsi postingan untuk setiap situs, atau dict per situs. Wajib diisi.
siteslist[str]Situs tujuan. Nilai bawaannya adalah ["GOOGLE", "FACEBOOK"].
post_typestrANNOUNCEMENT (bawaan), EVENT, OFFER, COVID19, atau PRODUCT.
cta_typestrTombol ajakan bertindak opsional; memerlukan cta_url.
cta_urlstrTujuan tombol CTA.
media_urlstrURL gambar publik opsional yang dilampirkan di setiap situs.
scheduled_datesdictRentang waktu {"startDatetime", "endDatetime"} opsional.
context_infodictDetail acara atau penawaran jika post_type memerlukannya.
additional_fieldsdictField camelCase tambahan dalam struktur datar yang digabungkan apa adanya.
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

Buat postingan ANNOUNCEMENT: pesan biasa dengan CTA dan media opsional. Nilai bawaan sites adalah ["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

Buat postingan EVENT dengan judul serta rentang waktu mulai dan selesai. Google mewajibkan judul acara; SDK memunculkan ValidationError jika judul tidak disertakan. start_day dan end_day adalah tanggal (YYYY-MM-DD); start_time dan end_time adalah string untuk ditampilkan, seperti "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

Buat postingan OFFER dengan kupon, diskon, dan ketentuan. title memberi label pada penawaran dan wajib diisi; start_day dan end_day (YYYY-MM-DD) membatasi masa berlakunya.

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

Buat postingan dari dict isi permintaan mentah. Anda meneruskan field dalam struktur datar di camelCase, lalu fungsi pembantu membungkusnya dalam objek input yang diwajibkan API sebelum mengirimkannya: isi permintaan yang dikirim melalui jaringan adalah {"input": {...}}, tidak pernah berupa struktur datar. locationIds harus sudah dienkode dalam base64. Utamakan metode pembuatan bertipe di atas untuk menggunakan argumen kata kunci, pengodean ID otomatis, dan validasi di sisi klien.

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

Wajib diisi: 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

Ambil postingan beserta konten, status publikasi per situs, dan analitiknya. Panggil metode ini secara berkala setelah pembuatan hingga status bernilai 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

Hapus postingan dan hapus juga dari setiap situs tempat postingan tersebut dipublikasikan.

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

posts.list_for_location

Ambil daftar kampanye postingan yang menargetkan suatu lokasi. Paginasi menggunakan offset: hasilnya berisi .records serta .pageInfo yang memuat totalPages, totalRecords, dan hasNextPage. Respons berada di dalam postsByLocation.

Rute ini menolak tag, sehingga sejak versi 0.5.3 SDK menerima argumen tersebut untuk kompatibilitas dengan versi sebelumnya dan tidak pernah mengirimkannya melalui jaringan. Gunakan posts.bulk_list_for_location jika Anda memerlukan pemfilteran berdasarkan tag.

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

Ambil kampanye massal (multilokasi) beserta status publikasi dan analitik per lokasi.

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

Ambil daftar kampanye massal (multilokasi) yang mencakup suatu lokasi. Parameter dan struktur hasilnya sama dengan 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)

Lihat juga

  • Lokasi: buat dan kelola lokasi tempat Anda memublikasikan postingan
  • Profil bisnis: periksa status sinkronisasi per lokasi
  • Analitik: analitik profil Google, Bing, Facebook