API thu thập dữ liệu địa phương của Google: Chuyển đổi gói địa phương thành JSON

Điểm nhấn chính:

• Một yêu cầu, một diễn viên. API Scrapeless Scraper biến gói địa phương của Google thành một POST duy nhất đối với diễn viên scraper.google.search. Không cần trình duyệt để điều khiển, không cần phân tích cú pháp đánh dấu.
• tbm: "lcl" là công tắc. Gửi đầu vào { "q": "các quán cà phê ở San Francisco", "tbm": "lcl" } và diễn viên trả về danh sách doanh nghiệp được hỗ trợ bởi bản đồ thay vì kết quả SERP trên web.
• Các trường cấu trúc, không phải HTML thô. Phản hồi là một đối tượng địa phương đã được phân tích — local_results.places[] với tiêu đề, đánh giá, số lượng đánh giá, địa chỉ, mức giá và hình thu nhỏ — được làm phẳng ở cấp độ đầu tiên.
• Các chip bộ lọc cũng đi kèm. suggested_searches mang các chip "Mở ngay / Được đánh giá cao nhất / Rẻ" dưới dạng URL của Google sẵn sàng để theo dõi, để bạn có thể chuyển hướng cùng một truy vấn mà không cần xây dựng lại nó.
• Không proxy, không xử lý chống bot ở phía bạn. Đường dẫn dân cư, định vị địa lý và xử lý diễn ra phía máy chủ; bạn gửi truy vấn và đọc JSON.
• Miễn phí để bắt đầu. Các tài khoản Scrapeless mới bao gồm tín dụng API Scraper miễn phí — đăng ký tại app.scrapeless.com.

Giới thiệu: biến gói địa phương của Google thành JSON

Gói địa phương của Google là bộ danh sách doanh nghiệp được đặt ở đầu tìm kiếm địa phương — các thẻ hỗ trợ bởi bản đồ mà Google hiển thị khi ai đó tìm kiếm "các quán cà phê ở San Francisco" hoặc "thợ sửa ống nước gần tôi." Mỗi thẻ mang tên, một danh mục, một xếp hạng sao, số lượng đánh giá, một địa chỉ và một mức giá. Đây là bề mặt mà các tìm kiếm có ý định địa phương thực sự nhấp vào, khiến nó trở thành tập dữ liệu phía sau nhiều công việc thực tế:

• Theo dõi thứ hạng địa phương — xem các doanh nghiệp nào chiếm giữ vị trí từ 1 đến N cho một truy vấn trong một thành phố nhất định.
• Theo dõi cạnh tranh — theo dõi xếp hạng và số lượng đánh giá của một đối thủ theo thời gian.
• Danh sách khách hàng tiềm năng — kéo các doanh nghiệp xếp hạng cho truy vấn theo danh mục cộng với địa phương vào một bảng có cấu trúc.
• Lấy mẫu đánh giá và cảm xúc — mỗi thẻ đưa ra một đoạn đánh giá đại diện mà bạn có thể thu thập ở quy mô lớn.
• Đo lường thị trường — đếm có bao nhiêu doanh nghiệp của một loại xếp hạng trong một thành phố và cách mà các xếp hạng của chúng phân cụm.

Lấy gói đó bằng tay có nghĩa là phải tạo ra một trang tìm kiếm nặng javascript, vượt qua giới hạn tỷ lệ của Google và viết các bộ chọn dựa trên các đánh dấu mà có thể thay đổi. API Scraper làm cả ba việc đó ở phía máy chủ và đưa cho bạn đối tượng đã được phân tích.

Tại sao chọn API Scraper

Một trình thu thập địa phương truyền thống là ba công việc được kết dính với nhau: vượt qua lớp chống bot, tạo trang và phân tích các thẻ. API Scrapeless Scraper gom chúng lại thành một cuộc gọi duy nhất. Bạn chỉ cần đặt tên cho diễn viên scraper.google.search, cung cấp truy vấn và tbm: "lcl", và nhận lại gói địa phương đã được phân tích.

• Không cần trình duyệt, không cần bộ phân tích nào để duy trì. Diễn viên sẽ làm cho và phân tích kết quả địa phương của Google; bạn nhận các trường, không phải là DOM để đi qua.
• Đường ra dân cư và định vị địa lý được xây dựng sẵn. Bạn gửi chuỗi truy vấn; diễn viên xử lý lớp mạng và việc tạo các đối tượng JavaScript.
• Một khóa, một dạng. Một x-api-token duy nhất xác thực cuộc gọi, và gói địa phương luôn quay trở lại với cùng một dạng đã được phân tích, vì vậy một khách hàng được viết một lần có thể tái sử dụng qua các truy vấn và thành phố.

Lấy khóa API của bạn trên gói miễn phí tại app.scrapeless.com. Gói địa phương của Google nằm trong gia đình Deep SerpApi bên cạnh các bề mặt tìm kiếm Google khác trong danh mục bảng giá.

Các yêu cầu cần có

• Một tài khoản Scrapeless và khóa API — đăng ký tại app.scrapeless.com.
• curl cho thử nghiệm nhanh, hoặc Python 3.10+ cho khách hàng bên dưới.
• Kiến thức cơ bản về HTTP và JSON.

Lưu trữ khóa của bạn trong môi trường để nó không bao giờ xuất hiện trong mã:

export SCRAPELESS_API_KEY=your_api_token_here

Yêu cầu

Gói địa phương sử dụng endpoint API Scraper v1 và diễn viên tìm kiếm Google. Việc chọn gói địa phương là một trường đầu vào — tbm được đặt là lcl.

• Endpoint: POST https://api.scrapeless.com/api/v1/scraper/request
• Xác thực: tiêu đề x-api-token: $SCRAPELESS_API_KEY
• Diễn viên: scraper.google.search (tbm: "lcl" chọn gói địa phương thay vì SERP trên web)

Nội dung yêu cầu là { "actor": "<name>", "input": { … } }:

{
  "actor": "scraper.google.search",
  "input": { "q": "các quán cà phê ở San Francisco", "tbm": "lcl" }
}

Ví dụ

Kiểm tra nhanh nhất là một curl. Nó gửi actor và input, và in ra đối tượng địa phương đã được phân tích:

curl -sS -X POST https://api.scrapeless.com/api/v1/scraper/request \
  -H "Content-Type: application/json" \
  -H "x-api-token: $SCRAPELESS_API_KEY" \
  -d '{
    "actor": "scraper.google.search",
    "input": { "q": "cửa hàng cà phê ở San Francisco", "tbm": "lcl" }
  }'

Lệnh tương tự trong Python đọc khóa từ môi trường và trả về phản hồi đã được phân tích:

import os
import json
import requests

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"


def scrape_local(query: str) -> dict:
    resp = requests.post(
        ENDPOINT,
        headers={
            "Content-Type": "application/json",
            "x-api-token": os.environ["SCRAPELESS_API_KEY"],
        },
        json={"actor": "scraper.google.search", "input": {"q": query, "tbm": "lcl"}},
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    data = scrape_local("cửa hàng cà phê ở San Francisco")
    for place in data["local_results"]["places"]:
        print(place["position"], place["title"], place["rating"], place["address"])

scraper.google.search làm phẳng gói địa phương đã được phân tích ở cấp độ trên cùng — không có bao bọc result để bóc tách. Đọc trực tiếp local_results.places[].

Nhận khóa API của bạn trên gói miễn phí: app.scrapeless.com

Những gì bạn nhận được

Actor trả về đối tượng địa phương đã được phân tích trực tiếp, cùng với một phong bì metadata chỉ vào HTML đã được lưu trữ. Chạy thu nhận cho q: "cửa hàng cà phê ở San Francisco", tbm: "lcl" đã trả về 20 địa điểm được xếp hạng:

// Hình dạng cấp trên từ một lần chạy trực tiếp scraper.google.search (tbm: "lcl").
// ảnh đại diện base64 và hầu hết các mục places[] đã được cắt ngắn; giá trị trường là thực.
{
  "local_results": {
    "places": [
      {
        "position": 1,
        "title": "The Coffee Berry SF",
        "type": " Cửa hàng cà phê",
        "rating": 4.9,
        "reviews": 588,
        "reviews_original": "(588)",
        "price": "$",
        "address": "1410 Lombard St",
        "phone": " $1–10 ",
        "hours": "4.9(588) ",
        "extensions": ["Espresso rất ngon, và nhân viên rất thân thiện và chào đón."],
        "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA…",
        "place_id": "",
        "place_id_search": "",
        "lsig": "",
        "gps_coordinates": { "latitude": 0, "longitude": 0 }
      },
      {
        "position": 8,
        "title": "Delah Coffee",
        "type": " Cửa hàng cà phê",
        "rating": 4.7,
        "reviews": 1100,
        "reviews_original": "(1.1K)",
        "price": "$",
        "address": "370 4th St",
        "phone": "Đặt hàng từ bên lề",
        "hours": "Ăn tại chỗ",
        "extensions": ["Ăn tại chỗ", "Đặt hàng từ bên lề", "Giao hàng không tiếp xúc"],
        "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA…",
        "place_id": "",
        "place_id_search": "",
        "lsig": "",
        "gps_coordinates": { "latitude": 0, "longitude": 0 }
      }
    ]
  },
  "search_information": {
    "query_displayed": "cửa hàng cà phê ở San Francisco",
    "organic_results_state": "Kết quả cho chính tả chính xác",
    "total_results": 0,
    "time_taken_displayed": ""
  },
  "suggested_searches": [
    {
      "name": "Mở ngay",
      "q": "Mở ngay cửa hàng cà phê ở San Francisco",
      "link": "https://www.google.com/search?…&udm=1&q=cửa+hàng+cà+phê+ở+San+Francisco+mở+ngay",
      "uds": "",
      "thumbnail": ""
    }
  ],
  "pagination": {},
  "metadata": {
    "engine": "google.search",
    "rawUrl": "https://api.scrapeless.com/storage/scrapeless.scraper.google.search/…html"
  }
}

Các trường trên mỗi thẻ places[]:

Các khóa cấp trên xung quanh các thẻ:

Một vài quan sát chân thật từ hình dạng đã thu thập:

• Đối tượng được làm phẳng. local_results.places[] là mảng bạn lặp qua - không có bao bọc result, không giống như một số đối tượng khác.
• reviews và reviews_original mang cùng một số theo hai cách. Một là một số nguyên cho toán học, một là chuỗi hiển thị của Google ((3.4K)). Đọc bất kỳ cái nào mà pipeline của bạn cần.
• phone và hours theo dõi những gì Google hiển thị trong mỗi ô thẻ. Đối với nhiều thẻ địa phương, đó là một khoảng giá (" $1–10 ") hoặc một cờ dịch vụ (Giao hàng bên lề, Ngồi lại ăn) thay vì số điện thoại cụ thể hoặc giờ mở cửa. Xử lý cả hai như văn bản tự do và xác nhận trước khi tin tưởng vào chúng.
• extensions chia nhánh theo thẻ. Hầu hết các thẻ trả về một đoạn đánh giá đơn lẻ; các thẻ với tùy chọn đặt hàng trả về danh sách dịch vụ (Ngồi lại ăn, Giao hàng bên lề, Giao hàng không tiếp xúc). Kiểm tra thẻ nào bạn nhận được.
• Các trường định danh và tọa độ có thể trở lại trống. place_id, place_id_search, lsig, và gps_coordinates có mặt trong sơ đồ nhưng có thể trống hoặc bằng không theo từng thẻ - coi các trường vắng mặt là có thể null.
• metadata.rawUrl là lối thoát của bạn. Nó lưu trữ HTML đã hiển thị nếu bạn cần một trường mà đối tượng đã phân tích không hiển thị.

Kết luận

Việc thu thập dữ liệu từ gói địa phương của Google giảm thành một quyết định và một yêu cầu: chọn đối tượng scraper.google.search, gửi { "q": "<query>", "tbm": "lcl" } với x-api-token của bạn, và đọc local_results.places[] trở lại dưới dạng JSON đã phân tích. Quay vòng proxy, render JavaScript, và phân tích đều chạy phía máy chủ, vì vậy cùng một client có thể chỉ vào bất kỳ thành phố hoặc danh mục nào bằng cách thay đổi chuỗi truy vấn. Đối với mặt trả lời AI của tìm kiếm Google, hướng dẫn về bộ thu thập thông tin Google AI Overview hướng dẫn cách thu thập khối trả lời và các tài liệu tham khảo tương tự. Đặt địa phương trong q, giữ tbm: "lcl" set, và coi các trường văn bản tự do và định danh là nullable.

Sẵn sàng để xây dựng Pipeline Tìm kiếm Địa phương Sử dụng AI của Bạn?

Tham gia cộng đồng của chúng tôi để yêu cầu một kế hoạch miễn phí và kết nối với các nhà phát triển xây dựng các pipeline tìm kiếm địa phương: Discord · Telegram.

Đăng ký tại app.scrapeless.com để nhận tín dụng API Scraper miễn phí, và chỉ định đối tượng scraper.google.search cho các truy vấn, thành phố, và danh mục mà pipeline của bạn cần.

Câu hỏi thường gặp

Q: Việc thu thập dữ liệu từ Google Local có hợp pháp không?

Gói địa phương là dữ liệu công khai. Quy định khác nhau theo từng khu vực và theo điều khoản dịch vụ của Google, vì vậy hãy xem xét các điều khoản liên quan và tham khảo ý kiến tư vấn pháp lý cho trường hợp sử dụng của bạn trước khi thực hiện ở quy mô lớn. Không bao giờ thu thập dữ liệu cá nhân được bảo vệ theo GDPR hoặc CCPA.

Q: Tôi có cần sử dụng proxy không?

Không. Đường chuyển dữ liệu khu dân cư và định tuyến địa lý đã được tích hợp vào đối tượng — bạn gửi truy vấn, đối tượng xử lý lớp mạng và render.

Q: tbm: "lcl" có tác dụng gì?

Nó chọn gói địa phương của Google - các danh sách doanh nghiệp có bản đồ hỗ trợ - thay vì SERP web. Bỏ qua nó hoặc thay đổi nó và cùng một đối tượng sẽ trả về các kết quả organic trên web cho truy vấn.

Q: Có bao nhiêu địa điểm quay lại?

Đối tượng trả về các thẻ mà Google xếp hạng cho truy vấn; lần chạy thu thập cho "cửa hàng cà phê ở San Francisco" đã trả về 20. Số lượng thay đổi theo truy vấn, danh mục, và địa phương.

Q: Làm thế nào tôi có thể nhắm đến một thành phố khác?

Đặt địa phương trong q. Đối tượng đọc chuỗi truy vấn, vì vậy cửa hàng cà phê ở Austin hoặc thợ sửa ống nước ở Chicago sẽ trả về gói địa phương cho khu vực đó.

Q: HTML thô ở đâu nếu một trường bị thiếu?

metadata.rawUrl lưu trữ một bản sao của trang đã hiển thị. Sử dụng nó để phân tích bất kỳ trường nào mà đối tượng không hiển thị trong đối tượng đã phân tích.

Q: Tôi có thể thực hiện điều này mà không cần một đại lý AI hoặc SDK không?

Có. Nó là HTTP thông thường - curl, requests trong Python, fetch trong Node, hoặc bất kỳ client HTTP nào cũng hoạt động trực tiếp. Không cần SDK.