Làm việc với dữ liệu vị trí

Hướng dẫn này trình bày cách tạo và chỉnh sửa dữ liệu vị trí. My Business Business Information API cho phép bạn làm những việc sau:

• Tạo vị trí mới.
• Xoá vị trí.
• Lấy thông tin vị trí theo tên tài nguyên.
• Liệt kê tất cả các vị trí cho một tài khoản.
• Cập nhật một hoặc nhiều trường cho một vị trí.

Bạn có thể sử dụng các địa điểm trong Google Ads, nhưng các địa điểm đó cần được xác minh để đủ điều kiện xuất hiện trên Google Tìm kiếm và Maps. Dữ liệu vị trí được biểu thị bằng tập hợp accounts.locations.

Trước khi bắt đầu

Trước khi sử dụng My Business Business Information API, bạn cần đăng ký ứng dụng của mình và lấy thông tin xác thực OAuth 2.0. Để biết thông tin chi tiết về cách bắt đầu sử dụng My Business Business Information API, hãy xem phần Thiết lập cơ bản.

Tạo vị trí

Bạn có thể sử dụng My Business Business Information API để tạo một vị trí mới cho doanh nghiệp bằng phương thức accounts.locations.create.

Để tạo một vị trí, hãy sử dụng các thông tin sau:

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

Xoá vị trí

Bạn có thể sử dụng My Business Business Information API để xoá một vị trí bằng phương thức locations.delete.

Để xoá một vị trí, hãy sử dụng lệnh sau:

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

Lấy thông tin vị trí theo tên

Nếu có nhiều doanh nghiệp liên kết với tài khoản của mình, bạn nên lấy một địa điểm duy nhất. Bạn có thể lọc theo tên doanh nghiệp để lấy một vị trí cụ thể bằng locations.get.

Để lấy thông tin vị trí theo tên, hãy sử dụng đoạn mã sau. Bạn phải chỉ định readMask để truy xuất các trường cụ thể. :

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

Trả về phiên bản Google Maps

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

Nếu không có kết quả, hệ thống sẽ trả về mã trạng thái HTTP 404 NOT FOUND. Để biết thêm thông tin chi tiết về cách quản lý nội dung cập nhật của Google, hãy xem bài viết Chấp nhận hoặc từ chối nội dung cập nhật.

Trả về dữ liệu vị trí mở rộng và trạng thái chỉnh sửa (v1alpha)

Để truy xuất cả dữ liệu vị trí do người bán cung cấp và dữ liệu vị trí mà người tiêu dùng nhìn thấy, cùng với các giai đoạn trong vòng đời chỉnh sửa theo từng trường (chẳng hạn như EDIT_LIFECYCLE_STAGE_PENDING hoặc EDIT_LIFECYCLE_STAGE_REJECTED), nguồn chỉnh sửa (SOURCE_API hoặc SOURCE_UI) và lý do vi phạm chính sách trong một lệnh gọi, hãy sử dụng locations.getExtended trong v1alpha:

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

Để xem ví dụ đầy đủ về phản hồi và thông tin chi tiết về cách diễn giải trạng thái chỉnh sửa theo từng trường và lỗi vi phạm chính sách, hãy xem bài viết Kiểm tra trạng thái chỉnh sửa cho các vị trí và thuộc tính.

Liệt kê vị trí

Khi quản lý một hoặc nhiều địa điểm, bạn có thể muốn liệt kê tất cả địa điểm được liên kết với tài khoản của mình. Sử dụng API accounts.locations.list để liệt kê tất cả các vị trí liên kết với một người dùng.

Để liệt kê tất cả các vị trí do người dùng đã xác thực trực tiếp sở hữu hoặc quản lý, hãy sử dụng phương thức sau:

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

Sử dụng ký tự đại diện '-' cho tài khoản trong URL yêu cầu để thêm trang thông tin thuộc sở hữu gián tiếp (thuộc sở hữu hoặc được quản lý thông qua một nhóm):

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

Lọc kết quả khi bạn liệt kê các vị trí

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

Cú pháp truy vấn cơ bản

Một quy định hạn chế có cú pháp như sau: <field><operator><value>, trong đó toán tử là EQUALS (=) hoặc HAS (:). Toán tử EQUALS (=) và HAS (:) tương đương với tất cả các trường ngoại trừ locationName (xem bảng bên dưới).

Dấu ngoặc kép được mã hoá thành "%22" và dấu cách được mã hoá thành dấu cộng (+).

Trừ phi có lưu ý khác, tất cả các phép so sánh đều là phép so sánh mã thông báo không phân biệt chữ hoa chữ thường. Ví dụ: "4 drive" sẽ khớp với "4, Privet Drive".

Kết hợp nhiều trường trong một truy vấn bộ lọc

API này cho phép AND kết nối tất cả các quy định hạn chế về trường. Tuy nhiên, đối với từ khoá OR, tất cả các quy tắc hạn chế đều phải áp dụng cho cùng một trường. Ví dụ: locationName=A HOẶC labels=B không được phép.

Ví dụ

Ví dụ sau đây cho thấy một biểu thức bộ lọc trả về tất cả các vị trí có tên "Pepé Le Pew". Nó cho thấy các danh mục cho "french_restaurant" hoặc "european_restaurant" và nhãn "mới mở".

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

Tìm theo khoảng cách hoặc tài khoản

Ví dụ sau đây cho thấy cách bạn có thể tìm kiếm các vị trí trong một khoảng cách nhất định từ một điểm địa lý:

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

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

Danh sách tất cả các trường bộ lọc được hỗ trợ

Sau đây là danh sách đầy đủ tất cả các trường có thể dùng để lọc:

Sắp xếp theo trường truy vấn

Bạn có thể sắp xếp kết quả theo tên doanh nghiệp hoặc mã cửa hàng, theo thứ tự tăng dần hoặc giảm dần. Nhiều tiêu chí sắp xếp được phân tách bằng dấu phẩy trong chuỗi orderBy, như trong ví dụ sau:

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

Vá một vị trí

Sử dụng My Business Business Information API để cập nhật một hoặc nhiều trường cho một vị trí bằng locations.patch.

Để thay đổi một hoặc nhiều trường cho một vị trí, hãy làm như sau:

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