Hướng dẫn này cho biết cách tạo và chỉnh sửa dữ liệu vị trí. API Thông tin doanh nghiệp của 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í.
- Lấy vị trí theo tên tài nguyên.
- Liệt kê tất cả vị trí của 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 địa điểm trong quảng cáo, nhưng địa điểm đó cần được xác minh thì mới đủ điều kiện xuất hiện trên 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 API Thông tin doanh nghiệp của 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 thông tin chi tiết về cách bắt đầu sử dụng API Thông tin doanh nghiệp của Doanh nghiệp của tôi, hãy xem phần 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 My Business để tạo một vị trí mới cho doanh nghiệp bằng accounts.locations.create.
Để tạo một vị trí, hãy sử dụng mã 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 API Thông tin doanh nghiệp của Doanh nghiệp của tôi để xoá một vị trí bằng lệnh locations.delete.
Để xoá một vị trí, hãy làm 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 chọn một vị trí duy nhất. Bạn có thể lọc theo tên doanh nghiệp để nhận được 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 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}
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ả, hệ thống sẽ trả về mã trạng thái HTTP 404 NOT FOUND. 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 nên liệt kê tất 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ả vị trí được liên kết với một người dùng.
Để liệt kê tất cả các vị trí do một 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 nội dung 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 để bao gồm cả những trang thông tin do bạn sở hữu gián tiếp (do bạn 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 đăng thông tin về 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 một biểu thức bộ 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
Quy tắc hạn chế có cú pháp sau: <field><operator><value>, trong đó toán tử là BẰNG (=) hoặc CÓ (:). Toán tử BẰNG (=) và CÓ (:) 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ó ghi chú khác, tất cả các phép so sánh đều là 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 truy vấn bộ lọc
API cho phép AND kết nối tất cả các hạn chế về trường. Tuy nhiên, đối với từ khoá HOẶC, tất cả các quy tắc hạn chế 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 lọc trả về tất cả vị trí có tên "Pepé Le Pew". Tệp này hiển thị các danh mục cho "french_restaurant" hoặc "european_restaurant" và nhãn "newly open" (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 biết 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}
Cách lọc các vị trí trong vòng 1.600 km 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ả 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:
| Trường | Nội dung mô tả và ví dụ |
|---|---|
| Trường so khớp chuỗi | |
title |
Tên doanh nghiệp trong thực tế
|
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 "gcid:". Nếu có nhiều danh mục, bộ lọc này sẽ khớp nếu í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 của đị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 của đị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, thì trường này sẽ bằng mã địa điểm của vị trí đó
|
openInfo.status |
Cho biết liệu Vị trí hiện có đang mở cửa kinh doanh hay không
(
|
labels |
Một tập hợp các chuỗi dạng tự do để cho phép bạn gắn thẻ cho doanh nghiệp của mình. Ngược lại 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 một nhãn đầy đủ, bao gồm cả cách viết hoa chứ không chỉ một mã thông báo. Ví dụ: Nếu một nhãn là "XX YY", thì "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í so với một điểm địa lý.
|
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 API Thông tin doanh nghiệp của My Business để 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:
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"
}