ทำงานกับข้อมูลตำแหน่ง

บทแนะนำนี้แสดงวิธีสร้างและแก้ไขข้อมูลตำแหน่ง My Business Business Information API ช่วยให้คุณทำสิ่งต่อไปนี้ได้

คุณสามารถใช้สถานที่ตั้งใน Google Ads ได้ แต่ต้องยืนยันสถานที่ตั้งเพื่อให้มีสิทธิ์ปรากฏใน Search และ Maps ข้อมูลตำแหน่งจะแสดงโดยคอลเล็กชัน accounts.locations

ก่อนเริ่มต้น

ก่อนใช้ My Business Business Information API คุณต้องลงทะเบียนแอปพลิเคชันและรับข้อมูลเข้าสู่ระบบ OAuth 2.0 ดูรายละเอียดเกี่ยวกับวิธีเริ่มต้นใช้งาน My Business Business Information API ได้ที่การตั้งค่าพื้นฐาน

สร้างสถานที่ตั้ง

คุณสามารถใช้ My Business Business Information API เพื่อสร้างสถานที่ตั้งใหม่สำหรับธุรกิจได้ด้วย accounts.locations.create

หากต้องการสร้างสถานที่ ให้ใช้สิ่งต่อไปนี้

HTTP
POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "title": "Google Sydney",
    "phoneNumbers": {
      "primaryPhone": "02 9374 4000"
     },
    "storefrontAddress": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUri": "https://www.google.com.au/",
    "regularHours": {
      "periods": [
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "WEDNESDAY",
          "closeDay": "WEDNESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "THURSDAY",
          "closeDay": "THURSDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "FRIDAY",
          "closeDay": "FRIDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        }
      ]
    },
    "categories": {
      "primaryCategory": {
        "name": "gcid:software_company"
      }
     }
}

ลบสถานที่ตั้ง

คุณสามารถใช้ My Business Business Information API เพื่อลบสถานที่ตั้งด้วย locations.delete

หากต้องการลบสถานที่ ให้ใช้คำสั่งต่อไปนี้

HTTP
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

รับตำแหน่งตามชื่อ

หากมีธุรกิจหลายแห่งที่เชื่อมโยงกับบัญชี คุณอาจต้องการรับข้อมูลของสถานที่ตั้งเดียว คุณสามารถกรองตามชื่อธุรกิจเพื่อดูสถานที่ตั้งที่เจาะจงได้ด้วย locations.get

หากต้องการดูสถานที่ตั้งตามชื่อ ให้ใช้ข้อมูลต่อไปนี้ คุณต้องระบุ readMask เพื่อดึงข้อมูลช่องที่ต้องการ :

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

แสดงเวอร์ชัน Google Maps

HTTP

หากต้องการแสดงผลสถานที่ตั้งในเวอร์ชัน Google Maps ให้เพิ่ม googleUpdated ต่อท้าย URL คำขอ ดังตัวอย่างต่อไปนี้

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

หากไม่มีผลลัพธ์ ระบบจะแสดงรหัสสถานะ HTTP 404 NOT FOUND ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดการการอัปเดตจาก Google ได้ที่หัวข้อยอมรับหรือปฏิเสธการอัปเดต

แสดงข้อมูลตำแหน่งที่ตั้งแบบขยายและสถานะการแก้ไข (v1alpha)

หากต้องการดึงข้อมูลตำแหน่งที่ผู้ขายระบุและข้อมูลตำแหน่งสำหรับผู้บริโภค พร้อมกับระยะต่างๆ ในวงจรการแก้ไขต่อฟิลด์ (เช่น EDIT_LIFECYCLE_STAGE_PENDING หรือ EDIT_LIFECYCLE_STAGE_REJECTED) แหล่งที่มาของการแก้ไข (SOURCE_API หรือ SOURCE_UI) และเหตุผลในการละเมิดนโยบายในการเรียกใช้ครั้งเดียว ให้ใช้ locations.getExtended ใน v1alpha ดังนี้

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

ดูตัวอย่างการตอบกลับแบบเต็มและรายละเอียดเกี่ยวกับการตีความสถานะการแก้ไขต่อฟิลด์และการละเมิดนโยบายได้ที่ตรวจสอบสถานะการแก้ไขสำหรับสถานที่ตั้งและแอตทริบิวต์

แสดงรายการตำแหน่งที่ตั้ง

เมื่อจัดการสถานที่ตั้งอย่างน้อย 1 แห่ง คุณอาจต้องการแสดงสถานที่ตั้งทั้งหมดที่เชื่อมโยงกับบัญชีของคุณ ใช้ API accounts.locations.list เพื่อแสดงสถานที่ตั้งทั้งหมดที่เชื่อมโยงกับผู้ใช้

หากต้องการแสดงสถานที่ตั้งทั้งหมดที่ผู้ใช้ที่ตรวจสอบสิทธิ์แล้วเป็นเจ้าของหรือจัดการโดยตรง ให้ใช้สิ่งต่อไปนี้

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

ใช้ไวลด์การ์ด '-' สำหรับบัญชีใน URL คำขอเพื่อรวมข้อมูลที่ไม่ได้เป็นเจ้าของโดยตรง (เป็นเจ้าของหรือจัดการผ่านกลุ่ม) ดังนี้

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

กรองผลลัพธ์เมื่อแสดงสถานที่ตั้ง

HTTP

คุณสามารถใช้ตัวกรองเพื่อจำกัดผลลัพธ์ที่แสดงเมื่อเรียกใช้ accounts.locations.list หากต้องการกรองคำขอ ให้เพิ่มนิพจน์ตัวกรองต่อท้าย URL ฐานดังที่แสดงในตัวอย่างนี้

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

ไวยากรณ์การค้นหาพื้นฐาน

ข้อจำกัดมีไวยากรณ์ดังนี้ <field><operator><value> โดยที่โอเปอเรเตอร์คือ EQUALS (=) หรือ HAS (:) โอเปอเรเตอร์ EQUALS (=) และ HAS (:) จะเทียบเท่ากันสำหรับทุกฟิลด์ ยกเว้น locationName (ดูตารางด้านล่าง)

เครื่องหมายคำพูดจะได้รับการเข้ารหัสเป็น "%22" และการเว้นวรรคจะได้รับการเข้ารหัสเป็นเครื่องหมายบวก (+)

การเปรียบเทียบทั้งหมดเป็นการเปรียบเทียบโทเค็นที่ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เว้นแต่จะระบุไว้เป็นอย่างอื่น เช่น "4 drive" จะตรงกับ "4, Privet Drive"

รวมหลายช่องในการค้นหาตัวกรอง

API อนุญาตให้ AND เชื่อมต่อข้อจำกัดของช่องทั้งหมด อย่างไรก็ตาม เมื่อใช้คีย์เวิร์ด OR ข้อจำกัดทั้งหมดจะต้องใช้กับช่องเดียวกัน เช่น ไม่อนุญาตให้ใช้ locationName=A หรือ labels=B

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงนิพจน์ตัวกรองที่แสดงผลสถานที่ตั้งทั้งหมดที่มีชื่อว่า "Pepé Le Pew" โดยจะแสดงหมวดหมู่ "french_restaurant" หรือ "european_restaurant" และป้ายกำกับ "newly open"

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

ค้นหาตามระยะทางหรือบัญชี

ตัวอย่างต่อไปนี้แสดงวิธีค้นหาสถานที่ตั้งภายในระยะทางที่กำหนดจากจุดทางภูมิศาสตร์

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

หากต้องการกรองสถานที่ตั้งที่อยู่ในรัศมี 1, 000 ไมล์จากโบลเดอร์ รัฐโคโลราโด สหรัฐอเมริกา ให้ทำดังนี้

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

รายการช่องตัวกรองที่รองรับทั้งหมด

ต่อไปนี้คือรายการช่องทั้งหมดที่ใช้สำหรับการกรองได้

Fields คำอธิบายและตัวอย่าง
ฟิลด์การจับคู่สตริง
title

ชื่อจริงของธุรกิจ

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (ตรงกับชื่อสถานที่ใดก็ได้ที่มี "Bajis" เป็นสตริงย่อย)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis" (ตรงกับชื่อสถานที่ใดก็ได้ที่มี "Bajis" เป็นโทเค็น/คำ)

categories

การรวมหมวดหมู่หลักและหมวดหมู่เพิ่มเติม โปรดทราบว่าต้องละเว้น "gcid:" หากมีหลายหมวดหมู่ ตัวกรองนี้จะจับคู่หากมีหมวดหมู่อย่างน้อย 1 หมวดหมู่ที่ตรงกับรูปแบบนี้

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

หมายเลขโทรศัพท์หลักในรูปแบบ E.164 (เช่น "+441234567890")

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

รหัสภูมิภาค CLDR ของประเทศ/ภูมิภาคของที่อยู่

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

เขตการปกครองย่อยระดับสูงสุดที่ใช้สำหรับที่อยู่ทางไปรษณีย์ของประเทศหรือภูมิภาค

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

ส่วนเมือง/เทศบาลของที่อยู่

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

รหัสไปรษณีย์ของที่อยู่

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

metadata.place_id

หากสถานที่ตั้งนี้ได้รับการยืนยันและเชื่อมต่อกับ/ปรากฏใน Google Maps ช่องนี้จะเท่ากับรหัสสถานที่ของสถานที่ตั้งนั้น

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

ระบุว่าสถานที่ตั้งเปิดให้บริการอยู่ในปัจจุบันหรือไม่ (OPEN, CLOSED_PERMANENTLY)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="OPEN"

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="CLOSED_PERMANENTLY"

labels

คอลเล็กชันสตริงรูปแบบอิสระที่ช่วยให้คุณติดแท็กธุรกิจได้ ค่านี้ต้องตรงกับป้ายกำกับแบบเต็มทุกประการ ซึ่งรวมถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ไม่ใช่แค่โทเค็นเท่านั้น ซึ่งแตกต่างจากช่องอื่นๆ ทั้งหมด เช่น หากป้ายกำกับคือ "XX YY" ทั้ง "XX" และ "xx yy" จะไม่ตรงกัน

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

ตัวระบุภายนอกสำหรับสถานที่ตั้งนี้ ซึ่งต้องไม่ซ้ำกันภายในบัญชีที่ระบุ

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

ฟังก์ชัน
distance

ช่วยให้คุณกรองตามระยะทางของสถานที่ตั้งจากจุดทางภูมิศาสตร์ได้

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

จัดเรียงตามช่องคำค้นหา

คุณสามารถจัดเรียงผลลัพธ์ตามชื่อธุรกิจหรือรหัสร้านค้า โดยเรียงจากน้อยไปมากหรือมากไปน้อยก็ได้ เกณฑ์การจัดเรียงหลายรายการจะคั่นด้วยคอมมาในสตริง orderBy ดังตัวอย่างต่อไปนี้

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

แก้ไขสถานที่ตั้ง

ใช้ My Business Business Information API เพื่ออัปเดตช่องอย่างน้อย 1 ช่องสำหรับสถานที่ตั้งด้วย locations.patch

หากต้องการเปลี่ยนช่องอย่างน้อย 1 ช่องสำหรับสถานที่ตั้ง ให้ใช้ข้อมูลต่อไปนี้

HTTP

เพิ่มช่องและค่าที่อัปเดตด้วยช่องสถานที่ตั้ง และใช้รายการช่องที่อัปเดตซึ่งคั่นด้วยคอมมาเป็นค่าสำหรับ fieldMask

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}