Hướng dẫn này trình bày cách tạo và chỉnh sửa dữ liệu vị trí. API Thông tin doanh nghiệp của tôi cho phép bạn làm những việc sau:
- Tạo vị trí mới.
- Xoá vị trí.
- Nhận 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 vị trí trong Google Ads, nhưng các vị trí cần được xác minh để đủ điều kiện xuất hiện trên Tìm kiếm và Maps. Dữ liệu vị trí sẽ được biểu thị trong bộ sưu tập accounts.locations.
Trước khi bắt đầu
Trước khi sử dụng API Thông tin doanh nghiệp của tôi, bạn cần đăng ký ứng dụng và lấy thông tin xác thực OAuth 2.0. Để biết chi tiết về cách bắt đầu sử dụng API Thông tin doanh nghiệp của tôi, hãy xem bài viết Thiết lập cơ bản.
Tạo vị trí
Bạn có thể sử dụng API Thông tin doanh nghiệp của tôi để tạo một địa điểm mới cho doanh nghiệp bằng accounts.locations.create.
Để tạo một vị trí, hãy sử dụng:
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 API Thông tin doanh nghiệp của tôi để xoá một vị trí bằng locations.delete.
Để xoá một vị trí, hãy làm theo các bước sau:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Nhận 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 bạn, thì bạn nên có một vị trí duy nhất. Bạn có thể lọc theo tên doanh nghiệp để xem vị trí cụ thể bằng locations.get.
Để nhận một vị trí theo tên, hãy sử dụng lệnh 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}
Quay lại phiên bản Google Maps
Để trả về phiên bản Google Maps của một vị trí, hãy thêm googleUpdated vào URL yêu cầu như trong ví dụ sau:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Nếu không có kết quả, thì mã trạng thái HTTP 404 NOT FOUND sẽ được trả về. Bạn có thể xem thêm thông tin chi tiết về cách quản lý nội dung cập nhật của Google tại đây.
Liệt kê vị trí
Khi quản lý một hoặc nhiều vị trí, bạn có thể muốn liệt kê tất cả các vị trí đượ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ả vị trí do người dùng đã xác thực sở hữu hoặc quản lý trực tiếp, hãy sử dụng:
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 để bao gồm các trang thông tin được sở hữu gián tiếp (được sở hữu hoặ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ê vị trí
Bạn có thể sử dụng bộ lọc để giới hạn kết quả được trả về khi gọi accounts.locations.list. Để lọc một yêu cầu, hãy thêm biểu thức lọc vào URL cơ sở như trong ví dụ sau:
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
Hạn chế có cú pháp sau: <field><operator><value>, trong đó toán tử là EQUALS (=) hoặc HAS (:). Các 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 dưới đây).
Dấu ngoặc kép được mã hoá dưới dạng "%22" và dấu cách dưới dạng dấu cộng (+).
Trừ phi có ghi chú khác, tất cả thông tin 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 VÀ kết nối tất cả các hạn chế về trường. Tuy nhiên, đối với từ khoá OR, bạn phải áp dụng tất cả các quy định hạn chế cho cùng một trường. Ví dụ: không được phép sử dụng locationName=A HOẶC labels=B.
Ví dụ:
Ví dụ sau đây cho thấy một biểu thức lọc trả về tất cả các vị trí có tên "Pepé Le Pew". Kết quả này hiển thị các danh mục của "Pháp_nhà hàng" hoặc "european_museum" 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 kiế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 vị trí trong một khoảng cách nhất đị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}
Để lọc vị trí trong phạm vi 1000 dặm tính từ Boulder, Colorado Hoa Kỳ:
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ả 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:
| Trường | Nội dung mô tả và ví dụ |
|---|---|
| Các trường so khớp chuỗi | |
title |
Tên thực của doanh nghiệp
|
categories |
Sự kết hợp giữa danh mục chính và danh mục bổ sung. Xin lưu ý rằng bạn phải bỏ qua thẻ "gcid:". Nếu có nhiều danh mục, bộ lọc này sẽ khớp nếu có ít nhất một danh mục khớp với mẫu này.
|
phone_numbers.primary_phone |
Số điện thoại chính ở định dạng E.164 (Ví dụ: "+441234567890").
|
storefront_address.region_code |
Mã vùng CLDR của quốc gia/khu vực trong địa chỉ
|
storefront_address.administrative_area |
Phân khu hành chính cao nhất dùng cho địa chỉ bưu chính của một quốc gia hoặc khu vực
|
storefront_address.locality |
Phần thành phố/thị trấn trong địa chỉ
|
storefront_address.postal_code |
Mã bưu chính của địa chỉ
|
metadata.place_id |
Nếu vị trí này đã được xác minh và được kết nối với/xuất hiện trên Google Maps, trường này bằng với mã địa điểm cho vị trí
|
openInfo.status |
Cho biết liệu Địa điểm đó có đang mở cửa kinh doanh hay không
(
|
labels |
Một bộ sưu tập các chuỗi dạng tự do để cho phép bạn gắn thẻ doanh nghiệp của mình. Trái ngược với tất cả các trường khác, giá trị này phải khớp chính xác với nhãn đầy đủ bao gồm cả cách viết hoa chứ không chỉ là mã thông báo. Ví dụ: Nếu nhãn là "XX YY", thì cả "XX" hoặc "xx yy" sẽ không khớp.
|
storeCode |
Giá trị nhận dạng bên ngoài cho vị trí này (phải là giá trị duy nhất trong một tài khoản nhất định)
|
| Hàm | |
distance |
Cho phép bạn lọc dựa trên khoảng cách của vị trí từ một điểm địa lý.
|
Sắp xếp theo trường cụm từ tìm kiếm
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í
Hãy sử dụng API Thông tin doanh nghiệp của tôi để 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 sử dụng:
Thêm các trường và giá trị đã cập nhật bằng trường vị trí, đồng thời sử dụng danh sách các trường đã cập nhật được phân tách bằng dấu phẩy làm giá trị cho fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}