API Hop

Dokumentacja

Dokumentacja API Hop

SimilarwebAPI — przegląd

Odpytuj ruch witryn, słowa kluczowe, linki zwrotne, odesłania, konkurentów i zaangażowanie przez uwierzytelnione punkty końcowe REST.

API Similarweb zapewnia 27 punktów końcowych danych tylko do odczytu pod /v1/similarweb. Używaj tego samego konta, klucza API, salda i historii zużycia co w innych API API Hop. Dostępność zależy od włączonej bramy i uprawnień klucza API; dokumentacja nie potwierdza dostępności produkcyjnej.

Uwierzytelnianie

Wyślij klucz API API Hop, a nie dane uwierzytelniające innego dostawcy:

http
Authorization: Bearer YOUR_API_KEY

Przykład żądania

Wszystkie publiczne operacje używają GET z parametrami zapytania i bez treści żądania. Zachowuj wielkość liter w ścieżkach i parametrach dokładnie według dokumentacji.

Obsługiwane są tylko dane światowe (country=999). Inne poprawne wartości kraju są zmieniane na 999 przed żądaniem do dostawcy i zwracają dane światowe, a nie dotyczące konkretnego kraju.

Dla punktów końcowych przyjmujących daty pierwszeństwo ma poprawny, pełny jawny zakres from/to. W punktach przyjmujących latest podana wartość nadal musi przejść istniejącą walidację formatu i danego punktu końcowego, ale jest pomijana przy wyborze zakresu i nie jest wysyłana do Similarweb; nie dodaje się domyślnego latest. Bez jawnego zakresu istniejące zachowanie latest, wartości domyślnych i okna pozostaje bez zmian. Ograniczenia historii nadal obowiązują, a punkty nieprzyjmujące latest nadal je odrzucają.

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"

Odesłania przychodzące używają jednej nazwy hosta w małym key, a nie keys. To key jest biznesowym parametrem zapytania wskazującym witrynę docelową, a nie danymi uwierzytelniającymi API; jest dozwolone tylko na jawnie dopuszczonych trasach GET Similarweb. Uwierzytelnianie API nadal używa Authorization, a inne pola uwierzytelnienia w zapytaniu pozostają zabronione. Wiersze są zwracane w Records, a nie Data. Dokładne pola każdej operacji opisuje pełny wykaz punktów końcowych.

Zakres

  • Wyszukiwanie: propozycje słów kluczowych, strony rankingowe, słowa kluczowe witryn, wyszukiwanie organiczne i płatne, słowa związane z marką.
  • Ruch witryny: zaangażowanie, wizyty, geografia, udział urządzeń, kanały i ruch społecznościowy.
  • Relacje: linki zwrotne, odesłania przychodzące, ruch wychodzący i podobne witryny.
  • Historia: osobne miesięczne szeregi wizyt, współczynnika odrzuceń, czasu wizyty i stron na wizytę.

Odpowiedzi

Udane odpowiedzi zachowują natywną treść JSON bez nowego opakowania success/data. Nazwy pól, nieznane pola, puste tablice i precyzja liczb pozostają bez zmian. Różne punkty końcowe mogą zwracać Data, Records lub inną natywną strukturę; nie zakładaj uniwersalnego pola wierszy.

Pusty udany wynik nie oznacza, że domena nie ma ruchu. Nieudanych żądań nie wolno traktować jako pustych danych. Zachowaj X-Request-Id i czas żądania do diagnozy.

Rozliczenia i stronicowanie

Standardowa cena to $0.0005 za udane żądanie, czyli $0.50 za 1,000 żądań, we wszystkich 27 punktach końcowych. Rozliczenie dotyczy żądania, a nie wiersza; udany pusty wynik nadal liczy się jako jedno żądanie. Każda kolejna strona jest osobnym żądaniem. Pierwszeństwo mają skonfigurowane ceny indywidualne konta. Żądania z nieprawidłowymi parametrami, bez uwierzytelnienia lub z niewystarczającym saldem nie są realizowane jako udane płatne wywołania. Nieudane żądania do dostawcy nie są obciążane opłatą.

Przed wywołaniem konto musi mieć co najmniej $0.10 dostępnych środków zgodnie z polityką minimalnego salda platformy. Standardowa opłata nadal wynosi $0.0005 za udane żądanie.

Używaj tylko pól stronicowania udokumentowanych dla wybranego punktu końcowego. Stronicowanie zwykle zaczyna się od 1; linki zwrotne używają Page i PageSize, podczas gdy inne tabele mogą używać page, pageSize lub rowsPerPage. Nie wysyłaj nieobsługiwanych pól rozmiaru strony.

Błędy

Błędy platformy mają poniższą strukturę; code jest kodem biznesowym platformy, a nie statusem HTTP:

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

Typowe statusy HTTP obejmują 400 nieprawidłowe zapytanie, 401 nieprawidłowy klucz API, 402 niewystarczające saldo, 403 odmowę dostępu do bramy, 429 limit częstotliwości i 5xx tymczasowy błąd dostawcy lub usługi. Nie ponawiaj błędnie sformułowanych żądań bez zmian.