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 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 vị trí trong Google Ads, nhưng các vị trí đó cần phải được được xác minh là đủ đ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 accounts.locations bộ sưu tập.
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 của bạn và lấy thông tin đăng nhập OAuth 2.0. Để biết thông tin chi tiết về cách bắt đầu với API Thông tin doanh nghiệp của tôi, hãy xem phần Thiết lập cơ bản.
Tạo một vị trí
Bạn có thể sử dụng API Thông tin doanh nghiệp của tôi để tạo vị trí mới cho doanh nghiệp có 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 để xóa vị trí có locations.delete.
Để xoá một vị trí, hãy làm như sau:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Nhận 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 có thể muốn nhận một vị trí duy nhất. Bạn có thể lọc theo doanh nghiệp để lấy tên miền cụ thể vị trí với locations.get.
Để nhận vị trí theo tên, hãy sử dụng các tùy chọn sau. Bạn phải chỉ định mặt nạ đọc để truy xuất các trường cụ thể. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Trả 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ả nào thì mã trạng thái HTTP 404 NOT FOUND sẽ là
bị trả lại. Bạn có thể xem thêm thông tin về việc 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ể liệt kê tất cả vị trí được liên kết với tài khoản của bạn. Sử dụng accounts.locations.list API để 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ả 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 như sau:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Hãy dùng ký tự đại diện '-' cho tài khoản trong URL yêu cầu để đưa
danh sách được sở hữu gián tiếp (sở hữu hoặc quản lý 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 điện accounts.locations.list. Để lọc một yêu cầu, hãy thêm biểu thức bộ lọc vào URL cơ sở như minh hoạ 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 định hạn chế có cú pháp sau đây:
<field><operator><value>,
trong đó toán tử là BẰNG (=) hoặc HAS (:). BẰNG (=) và CÓ (:)
toán tử 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á là "%22" và dấu cách ở dạng dấu cộng (+).
Trừ phi có ghi chú khác, mọi thông tin so sánh đều không phân biệt chữ hoa chữ thường các so sánh. 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 lọc
API này cho phép VÀ kết nối tất cả hạn chế đối với trường. Tuy nhiên,
khi nói đến từ khoá OR, tất cả các quy tắc hạn chế đều phải được áp dụng cho cùng một từ khoá
. Ví dụ: locationName=A HOẶC labels=B thì không
được phép.
Ví dụ:
Ví dụ sau đây cho thấy biểu thức bộ lọc trả về tất cả vị trí có tên "Pepé Le Pew". Mục này hiển thị các danh mục cho "french_nhà hàng" hoặc "Châu_âu_nhà_hàng" 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 cho thấy cách bạn có thể tìm kiếm vị trí trong một khoảng cách so với 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 các vị trí trong phạm vi 1000 dặm của 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 |
Doanh nghiệp tên thực tế
|
categories |
Tổ hợp danh mục chính và danh mục bổ sung. Lưu ý rằng "gcid:" phải được bỏ qua. 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 danh mục 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 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 đến/xuất hiện trên Google Maps, thì trường này bằng với mã địa điểm cho vị trí
|
openInfo.status |
Cho biết Vị trí hiện có đang mở cửa kinh doanh hay không
(
|
labels |
Tập hợp các chuỗi dạng tự do để cho phép bạn gắn thẻ doanh nghiệp của mình. Trong 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 bao gồm cách viết hoa chứ không chỉ mã thông báo. Ví dụ: Nếu nhãn là "XX YY", sau đó không phải là "XX" hoặc "xx yy" sẽ khớp.
|
storeCode |
Giá trị nhận dạng bên ngoài của vị trí này. Giá 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
thứ tự 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 tôi để cập nhật một hoặc nhiều trường cho một vị trí có locations.patch.
Để thay đổi một hoặc nhiều trường cho một vị trí, hãy sử dụng cách sau:
Thêm các trường và giá trị đã cập nhật với trường vị trí, rồ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"
}