API Hop

Tài liệu

Tài liệu API Hop

SimilarwebAPI

>-

SimilarwebAPI cung cấp 27 điểm cuối dữ liệu chỉ đọc dưới /v1/similarweb. Dùng cùng tài khoản, khóa API, số dư và lịch sử sử dụng với các API API Hop khác. Khả dụng phụ thuộc cổng đã bật và quyền khóa API; tài liệu không xác nhận khả dụng trên môi trường sản xuất.

Xác thực

Gửi khóa API API Hop của bạn, không phải thông tin xác thực bên thứ ba:

http
Authorization: Bearer YOUR_API_KEY

Ví dụ yêu cầu

Mọi thao tác công khai dùng GET với tham số truy vấn và không có thân yêu cầu. Giữ nguyên chữ hoa/chữ thường trong đường dẫn và tham số theo tài liệu.

Chỉ hỗ trợ dữ liệu toàn cầu (country=999). Giá trị quốc gia hợp lệ khác được đổi thành 999 trước yêu cầu thượng nguồn và trả dữ liệu toàn cầu, không phải riêng quốc gia.

Với điểm cuối chấp nhận ngày, khoảng from/to rõ ràng, hợp lệ và đầy đủ được ưu tiên. Ở điểm cuối chấp nhận latest, giá trị được cung cấp vẫn phải vượt xác thực định dạng hiện có và riêng của điểm cuối, nhưng bị bỏ qua khi chọn khoảng và không được gửi tới Similarweb; không thêm latest mặc định. Khi không có khoảng rõ ràng, hành vi latest, mặc định và cửa sổ hiện có giữ nguyên. Hạn chế lịch sử vẫn áp dụng, và điểm cuối không chấp nhận latest vẫn từ chối nó.

bash
curl --get "https://api.apihop.ai/v1/similarweb/websites/incoming-referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "key=example.com" \
  --data-urlencode "country=999" \
  --data-urlencode "page=1"

Nguồn giới thiệu đến dùng một tên máy chủ key viết thường, không phải keys. key này là tham số truy vấn nghiệp vụ cho website đích, không phải thông tin xác thực API; nó chỉ được phép trên tuyến Similarweb GET trong danh sách cho phép cụ thể. Xác thực API vẫn dùng Authorization và các trường thông tin xác thực truy vấn khác vẫn bị cấm. Hàng kết quả trả trong Records, không phải Data. Xem tham chiếu điểm cuối đầy đủ để biết trường chính xác của mỗi thao tác.

Phạm vi dữ liệu

  • Tìm kiếm: gợi ý từ khóa, trang xếp hạng, từ khóa website, tìm kiếm tự nhiên và trả phí, từ khóa thương hiệu.
  • Lưu lượng website: tương tác, lượt truy cập, địa lý, cơ cấu thiết bị, kênh và lưu lượng xã hội.
  • Quan hệ: liên kết ngược, nguồn giới thiệu đến, lưu lượng đi và website tương tự.
  • Lịch sử: chuỗi riêng theo tháng về lượt truy cập, tỷ lệ thoát, thời lượng truy cập và số trang mỗi lượt truy cập.

Phản hồi

Phản hồi thành công giữ nguyên thân JSON gốc, không thêm lớp bao success/data mới. Tên trường, trường không rõ, mảng rỗng và độ chính xác số giữ nguyên. Điểm cuối khác nhau có thể trả Data, Records hoặc cấu trúc gốc khác; đừng giả định có trường hàng chung.

Kết quả rỗng thành công không có nghĩa tên miền không có lưu lượng. Không được coi yêu cầu thất bại là dữ liệu rỗng. Giữ X-Request-Id và thời gian yêu cầu để khắc phục.

Tính phí và phân trang

Giá tiêu chuẩn là $0.0005 mỗi yêu cầu thành công, hoặc $0.50 mỗi 1,000 yêu cầu, cho cả 27 điểm cuối. Tính phí theo yêu cầu, không theo hàng; kết quả rỗng thành công vẫn tính là một yêu cầu. Mỗi trang tiếp là một yêu cầu riêng. Giá riêng của tài khoản được ưu tiên nếu có cấu hình. Yêu cầu có tham số không hợp lệ, thiếu xác thực hoặc không đủ số dư không được xử lý như lời gọi thành công có phí. Không tính phí yêu cầu thượng nguồn thất bại.

Tài khoản phải có ít nhất $0.10 khả dụng trước lời gọi, theo chính sách số dư tối thiểu của nền tảng. Phí tiêu chuẩn vẫn là $0.0005 mỗi yêu cầu thành công.

Chỉ dùng trường phân trang được mô tả cho điểm cuối đã chọn. Phân trang thường bắt đầu từ 1; liên kết ngược dùng Page và PageSize, còn bảng khác có thể dùng page, pageSize hoặc rowsPerPage. Không gửi trường kích thước trang không được hỗ trợ.

Lỗi

Lỗi nền tảng dùng cấu trúc sau; code là mã nghiệp vụ nền tảng, không phải trạng thái HTTP:

json
{"success":false,"error":{"code":10000,"message":"Invalid request parameters"},"requestId":"..."}

Trạng thái HTTP phổ biến gồm 400 truy vấn không hợp lệ, 401 khóa API không hợp lệ, 402 số dư không đủ, 403 truy cập cổng bị từ chối, 429 giới hạn tốc độ và 5xx lỗi thượng nguồn hoặc dịch vụ tạm thời. Không thử lại yêu cầu sai định dạng mà không sửa.