wersja API: v1.10 - stan na dzień 10 stycznia 2022
Webmity to aplikacja marketingowa oferująca możliwość tworzenia wysokiej jakości stron satelitarnych, przechwytujących wartościowy ruch (generowanie leadów sprzedażowych). Poniższa dokumentacja API skierowana jest do developerów, właścicieli kont klienckich i agencji chcących zintegrować własne rozwiązania ze swoim kontem.
API systemu Webmity zostało zrealizowane w modelu REST. Wykorzystuje protokół szyfrowany HTTPS (połączenia nieszyfrowane nie są obsługiwane). Komunikacja polega na wysłaniu żądania POST (parametry wysłane metodą POST mają wyższy priorytet) lub GET (maksymalna długość 8100 znaków) pod adres https://app.webmity.com/apiv1
z użyciem kluczy autoryzacyjnych APIKEY oraz SECRETKEY. Dane zwracane są w formacie JSON. Wymiana danych odbywa się z użyciem kodowania UTF-8
. W limicie długości parametrów, należy uwzględnić znaki UTF-8
, które nie są liczone jako jeden znak.
API zbudowane jest z metod pogrupowanych tematycznie w moduły. Uprawnienia dostępu do poszczególnych modułów nadawane są przez administratora.
Żądania dotyczące domen IDN można kierować do api w dowolnej formie, odpowiedź zaź zwracana jest zawsze z znakami specjalnymi. Lista domen w zapytaniu nie może przekraczać 250 nazw.
Ścieżka dostępu:
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=MODULE&action=ACTION&key1=value1&...
gdzie:
Nazwa | Opis |
---|---|
apikey | Twój klucz APIKEY - 16 znakowy losowy ciąg znaków alfanumerycznych, przykład: 218e37ea356d0dna |
secretkey | Twój SECRETKEY - 32 znakowy losowy ciąg znaków alfanumerycznych, przykład: d943e000b7a3d1be2d1b5a1eb699b847 |
module | Nazwa modułu |
action | Nazwa akcji do wykonania |
key1 | Dodatkowy parametr dla akcji. Opis parametrów wymaganych przez akcję znajdziesz w przy jej opisie. |
W parametrach należy umieścić odpowiedni typ danych. Mimo iż w praktyce nie można zdefiniować typu zmiennej w QueryString, nadal serwer może odrzucić dane które nie mogą być poprawnie zinterpretowane (np. dla bool wartość "pizza"). Dodatkowe wymagania dla parametrów są zapisane w opisie akcji.
Typ parametru | Dopuszczalne wartości |
---|---|
Boolean | Przyjmowane wartości: true , yes , tak , 1 lub false , no , nie , 0 . Inne wartości są traktowane jak brak parametru. |
Integer | Liczba z zakresu -9223372036854775808 - 9223372036854775807 . Inne wartości są rzutowane jako tekst na integer. |
String | Tekst w kodowaniu utf-8 , niepoprawne znaki spowodują błąd 1007 . |
Enum | Jedna z wartości podanych w opisie parametru. Inne wartości są traktowane jak brak parametru. |
Przykładowe zapytanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=ping
Odpowiedź jest zwracana w formacie obiektu JSON.
Struktura odpowiedzi może zostać przedstawiona za pomocą prostej tabeli:
Nazwa indeksu | Typ | Opis |
---|---|---|
status | Integer | Otrzymuje wartość 1 gdy zapytanie jest poprawne i dostępne są dane zwrotne, w każdym innym przypadku 0 . |
data | Object lub Array | Występuje gdy status jest równy 1 . Opis przyjmowanych wartości znajduje się w poszczególnych akcjach. |
error | Integer | Występuje gdy status jest równy 0 . Znaczenie błędów można odczytać z sekcji Kody błędów |
message | String | Może wystąpić gdy status jest równy 0 . Występuje sporadycznie, nie jest równoznaczny z kodem błędu i jedynie opisuje specyficzny dla danej akcji błąd. |
Przykładowa odpowiedź
{ "status": 1, "data": { "pong": 1370044800 } }
Uwaga! Dla czytelności dokumentacji kod odpowiedzi został sformatowany. W odpowiedzi na żądanie API zwracany jest niesformatowany obiekt JSON.
Moduł zawiera zestaw akcji pozwalających na odczyt i modyfikację stron reklamowych dostępnych na koncie. W przyszłości zostanie udostępnione dodatkowe możliwości.
Wyświetla aktualną listę stron reklamowych (domen) zarejestrowanych na koncie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=list
Dodatkowe parametry:
Nazwa indeksu | Wartość | Opis |
---|---|---|
details opcjonalne |
true lub false | Rozszerza zwracaną listę o parametry marketingowe domen: referring domains, backlinks, site, pagerank, trust i power gdzie 2 ostatnie to autorskie współczynniki (skala od 0 do 100). Parametr trust wyraża współczynnik zaufania Google'a do domeny a power określa jej moc pozycjonującą. Im wyższa wartość tym lepiej. |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "id": 1, "name": "domena1.test.pl", "created": 1380733092, "expiration": 1412269151, "active": "on", "status": "active", "articles": 18 }, "domena2.test.pl": { "id": 2, "name": "domena2.test.pl", "created": 1389098973, "expiration": 1420635407, "active": "on", "status": "active", "articles": 24 }, "domena3.test.pl": { "id": 3, "name": "domena3.test.pl", "created": 1400172964, "expiration": 1431709022, "active": "off", "status": "active", "articles": 6 } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator domeny w systemie |
name | String | Nazwa domeny |
created | Integer | Znacznik czasowy zawierający datę rejestracji domeny |
expiration | Integer or Null | Zwraca znacznik czasowy daty wygaśnięcia domeny lub null gdy niedostępny |
active | String | Czy domena jest włączona on , off |
status | String | Tekstowy status domeny w języku angielskim. Możliwe wartości: pending , active , expired , unknown |
articles | Integer | Liczba artykułów w domenie |
language | String | Język strony, np. pl_PL lub en_US |
backlinks | Integer | Dla details=true |
site | Integer | Dla details=true |
pagerank | Integer | Dla details=true |
referring | Integer | Dla details=true |
trust | Integer | Dla details=true |
power | Integer | Dla details=true |
Zwraca aktualny zrzut ekranu strony zakodowany za pomocą algorytmu base64. Zrzut ekranu odświeżany jest maksymalnie co 3 dni.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=screenshot&domains=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domains | Nazwy domen rozdzielone średnikiem (; ) lub pojedyncza domena |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "image": "b2JyYXplayB6YWtvZG93YW55IHogdcW8eWNpZW0gYmFzZTY0", "mime": "image\/png" }, "domena2.test.pl": { "image": null } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
image | String or Null | Zawiera obrazek zakodowany z użyciem base64 lub null gdy np. nie został jeszcze wykonany |
mime opcjonalne |
String | Typ mime obrazu |
Wymuszenie aktualizacji strony reklamowej na serwerze satelitarnym (opublikowanie zmian).
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=commit&domain=domena1.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domain | Nazwa domeny |
Odpowiedź
{ "status": 1, "data": "ok" }
Odpowiedź zawiera string
"ok".
Zawiera zestaw akcji listujący wszystkie artykuły i kategorie przypisane do konkretnej domeny wraz z szczegółowymi informacjami dodatkowymi np. ilość znaków.
Dodanie nowego artykułu w danej domenie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=add&domain=domena1.test.pl&name=Kompania%20w%C4%99glowa&title=Kompania%20w%C4%99glowa&text=%3Cp%3EZatrudniaj%C4%85ca%20blisko%2060%20tys.%20os%C3%B3b%20Kompania%20W%C4%99glowa%20znajduje%20si%C4%99%20w%20krytycznym%20po%C5%82o%C5%BCeniu.%3C%2Fp%3E
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domain | Nazwa domeny |
name | Nazwa, maksymalnie 150 znaków. |
title | Tytuł, maksymalnie 150 znaków. |
text | Treść, może zawierać tagi html, jednak kod nie jest optymalizowany tak jak w panelu, zalecamy formatowanie tekstu przez panel. Kolejne akapity należy umieszczać w tagach <p> . |
category opcjonalne |
Id kategorii lub 0 (brak). |
description opcjonalne |
Opis artykułu, maksymalnie 250 znaków. |
keywords opcjonalne |
Słowa kluczowe lub tagi, oddzielone przecinkiem, maksymalnie 250 znaków. |
date opcjonalne |
Planowana data publikacji w formacie DD-MM-YYYY lub jako znacznik czasowy UNIXTIMESTAMP . |
check opcjonalne |
Sprawdzanie unikalności tekstu, domyślnie true . W przypadku duplikatu zwracany jest błąd 2099 . |
Odpowiedź
{ "status": 1, "data": { "id": 20 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator nowego artykułu w sysytemie |
Edycja artykułu w danej domenie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=edit&article=20&name=Kompania%20w%C4%99glowa&title=Kompania%20w%C4%99glowa
Porada: Edycja umożliwia zmianę jednej lub wielu kolumn. Daną wartość można wyczyścić podając pusty parametr. Pola, które nie mają być edytowane, NIE MOGĄ pojawić się w zapytaniu. Brak jakiegokolwiek pola poskutkuje błędem 2001
. Nie można też podać pustych wartości dla name
, title
, text
, inaczej zostanie zwrócony błąd 1005
.
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
article wymagane |
Identyfikator artykułu |
name | Nazwa, maksymalnie 150 znaków, nie może być pusta. |
title | Tytuł, maksymalnie 150 znaków, nie może być pusty. |
text | Treść, nie może być pusta, może zawierać tagi html, jednak kod nie jest optymalizowany tak jak w panelu, zalecamy formatowanie tekstu przez panel. Kolejne akapity należy umieszczać w tagach <p> . |
category | Id kategorii lub 0 (brak). |
description | Opis artykułu, maksymalnie 250 znaków. |
keywords | Słowa kluczowe lub tagi, oddzielone przecinkiem, maksymalnie 250 znaków. |
date | Planowana data publikacji w formacie DD-MM-YYYY lub jako znacznik czasowy UNIXTIMESTAMP . |
check | Sprawdzanie unikalności tekstu, domyślnie true . W przypadku duplikatu zwracany jest błąd 2099 . Działa tylko przy podaniu parametru text |
Odpowiedź
{ "status": 1, "data": { "id": 20 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator artykułu w sysytemie |
Wyświetla aktualną listę artykułów danej domeny.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=list&domains=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domains | Nazwy domen rozdzielone średnikiem (; ) lub pojedyncza domena |
content | Zwracanie treści i plików, domyślnie false . |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": [ { "id": 1890, "name": "Ostrze\u017cenie przed zawiejami", "title": "Ostrze\u017cenie przed zawiejami", "publicated": 1390867200, "charcount": 1818, "category": "Jeden", "description": "Na og\u00f3\u0142 pochmurno, \u015bnie\u017cnie, wietrznie i mro\u017ano - takie s\u0105 prognozy na najbli\u017csze dni. Na p\u00f3\u0142nocnym-wschodzie Polski termometry maj\u0105 wskazywa\u0107 w \u015brod\u0119 nawet minus 10...", "tags": [ "organizm" ] }, { "id": 240, "name": "Policja: Jed\u017amy wolniej i ostro\u017cniej", "title": "Policja: Jed\u017amy wolniej i ostro\u017cniej", "publicated": 1390867200, "charcount": 1083, "category": "Dwa", "description": "Jed\u017amy wolniej i ostro\u017cniej - apeluje policja. W ca\u0142ym kraju jazd\u0119 utrudnia zalegaj\u0105cy \u015bnieg albo b\u0142oto po\u015bniegowe i \u015bliska nawierzchnia. - W takich warunkach dochodzi...", "tags": [ "organizm" ] } ], "domena2.test.pl": [ { "id": 560, "name": "Kompania w\u0119glowa", "title": "Kompania w\u0119glowa", "publicated": 1381401970, "charcount": 3766, "category": "Wegiel brunatny", "description": "Zatrudniaj\u0105ca blisko 60 tys. os\u00f3b Kompania W\u0119glowa znajduje si\u0119 w krytycznym po\u0142o\u017ceniu. Do sierpnia firma mia\u0142a 341 mln z\u0142 straty. Wed\u0142ug informacji "Rzeczpospolitej" jej sytuacja finansowa w tym roku pozostaje pod tak du\u017c\u0105 presj\u0105, \u017ce g\u0142\u00f3wnym ce", "tags": [ "gerardin", "musi", "przysz\u0142o\u015bci", "sytuacji", "wobec" ] }, { "id": 78, "name": "Reprezentacja polski", "title": "Reprezentacja polski", "publicated": 1381402136, "charcount": 1202, "category": "Pi\u0142ka no\u017cna", "description": "Tylko cud mo\u017ce sprawi\u0107, \u017ce pi\u0142karska reprezentacja Polski pod wodz\u0105 Waldemara Fornalika wywalczy awans do mistrzostw \u015bwiata w Brazylii. Z historii znamy jednak wielu...", "tags": [ "gerardin", "musi", "przysz\u0142o\u015bci", "sytuacji", "wobec" ] } ] } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator artykułu w sysytemie |
name | String | Nazwa artykułu |
title | String | Tytuł artykułu |
publicated | Integer | Zwraca znacznik czasowy daty publikacji artykułu |
charcount | Integer | Ilość znaków artykułu liczona ze spacjami |
category | String | Nazwa kategorii do której artykuł został przypisany |
description | String | Opis artykułu |
tags | Array[String] | Słowa kluczowe artykułu |
url | String | Link do artykułu |
text | String | Treść artykułu (HTML). Dla content=true |
files | Array[String] | Linki do załączonych plików. Dla content=true |
categoryid | Integer or null | Identyfikator kategorii |
Wyświetla ilość wizyt dla artykułu w podanym miesiącu lub dniu.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=visits&year=2014&month=4&day=28&articles=1890;78
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
articles | Identyfikatory artykułów rozdzielone średnikiem (; ) lub pojedyncza domena |
year | Rok którego statystyki chcemy otrzymać |
month | Miesiąc którego statystyki chcemy otrzymać |
day opcjonalne |
Dzień którego statystyki chcemy otrzymać |
Odpowiedź
{ "status": 1, "data": { "1890": { "20140428": { "pages": 18, "visits": 11 } }, "70": { "20140428": { "pages": 36, "visits": 2 } } } }
Odpowiedź w postaci object
, gdzie indeksy to identyfikatory artykułów, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
pages | Integer | Ilość odsłon wygenerowana przez unikalnych użytkowników |
visits | Integer | Ilość unikalnych wizyt użytkowników |
Wyświetla aktualną listę kategorii danej domeny.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=categories&domains=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domains | Nazwy domen rozdzielone średnikiem (; ) lub pojedyncza domena |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": [ { "id": 12, "name": "Jeden", "title": "", "url": null }, { "id": 13, "name": "Dwa", "title": "Drugi", "url": null } ], "domena2.test.pl": [ { "id": 17, "name": "Wegiel brunatny", "title": "", "url": "\/wegiel-b.html" }, { "id": 19, "name": "Pi\u0142ka no\u017cna", "title": "", "url": null } ] } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | String | Identyfikator kategorii |
name | String | Nazwa kategorii |
title | String | Title (opcjonalne) |
url | String or Null | Zdefiniowany adres URL (opcjonalne) |
Dodanie nowej kategorii w danej domenie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=categoryadd&domain=domena1.test.pl&name=Kategoria+1
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domain | Nazwa domeny |
name | Nazwa, maksymalnie 150 znaków. |
title opcjonalne |
Tytuł, maksymalnie 150 znaków. |
url opcjonalne |
Adres url dla kategorii |
Odpowiedź
{ "status": 1, "data": { "id": 20 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator nowej kategorii w sysytemie |
Moduł do zarządzania plikami.
Pozwala na wgranie zdjęć i dokumentów do menadżera plików. Przed wgraniem sprawdzana jest obecność danego pliku, a w przypadku znalezienia duplikatu zwracany jest link do oryginalnego pliku. W dziale Przykładowe skrypty znajduje się użyteczny kod, który może posłużyć jako wzorzec. Akcja może zwrócić błąd z zakresu 2071
-2076
.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=file&action=upload
Dodatkowe parametry:
Nazwa indeksu | Wartość | Opis |
---|---|---|
type opcjonalne |
image lub doc |
Pozwala na wybranie zakładki do której zostanie wgrany plik |
Pliki:
Nazwa indeksu | Opis |
---|---|
file | Plik wysłany jako POST multipart/form-data |
Odpowiedź
{ "status": 1, "data": { "file_status": "uploaded", "url": "\/resources\/library\/image\/aabbccdd\/aaaabbbbccccddddeeeeffff_t3.png" } }
Odpowiedź w postaci obiektu o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
file_status | String | uploaded dla poprawie wgranego pliku lub found jeśli plik został już znaleziony na koncie |
url | String | Adres względny do obrazu, powinien być używany w img src w niezmienionej postaci |
Moduł do zarządzania kampaniami.
Wyświetla aktualną listę kampanii na koncie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=list
Dodatkowe parametry:
Nazwa indeksu | Wartość | Opis |
---|---|---|
details opcjonalne |
true lub false | Rozszerza zwracaną listę o parametry marketingowe domen: referring domains, backlinks, site, pagerank, trust i power (więcej domain / list) oraz myreferring i mybacklinks, które odnoszą się do linków z własnych stron reklamowych. |
Odpowiedź
{ "status": 1, "data": [ { "id": 1, "name": "domena1.test.pl", "created": 1380733092 }, { "id": 2, "name": "domena2.test.pl", "created": 1389098973 }, { "id": 3, "name": "domena3.test.pl", "created": 1400172964 } ] }
Odpowiedź w postaci array
, gdzie wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator kampanii w systemie |
name | String | Nazwa domeny |
created | Integer | Znacznik czasowy zawierający datę dodania kampanii |
backlinks | Integer | Dla details=true |
site | Integer | Dla details=true |
pagerank | Integer | Dla details=true |
referring | Integer | Dla details=true |
trust | Integer | Dla details=true |
power | Integer | Dla details=true |
mybacklinks | Integer | Dla details=true Z własnych stron reklamowych. |
myreferring | Integer | Dla details=true Z własnych stron reklamowych. |
Zwraca aktualny zrzut ekranu strony zakodowany za pomocą algorytmu base64. Zrzut ekranu odświeżany jest maksymalnie co 3 dni.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=screenshot&campaigns=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
campaigns | Nazwy kampanii rozdzielone średnikiem (; ) lub pojedyncza domena |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "image": "b2JyYXplayB6YWtvZG93YW55IHogdcW8eWNpZW0gYmFzZTY0", "mime": "image\/png" }, "domena2.test.pl": { "image": null } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy kampanii, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
image | String or Null | Zawiera obrazek zakodowany z użyciem base64 lub null gdy np. nie został jeszcze wykonany |
mime opcjonalne |
String | Typ mime obrazu |
Wyświetla wszystkie monitorowane słowa kluczowe wraz z aktualnymi pozycjami, opcjonalnie z historią pozycji dla wybranej daty.
Uwaga Jeśli zostanie wybranych kilka wyszukiwarek do monitorowania. Funkcja position może wtedy zwracać pozycje z danego dnia dla przypadkowej wyszukiwarki. Ewentualne zapotrzebowanie na wsparcie wielu wyszukiwarek w API prosimy zgłaszać na adres podany w stopce.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=position&campaigns=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
campaigns | Nazwy kampanii rozdzielone średnikiem (; ) lub pojedyncza kampania |
year | Rok z którego raport pozycji chcemy pobrać |
month | Miesiąc z którego raport pozycji chcemy pobrać |
day opcjonalne |
Dzień z którego raport pozycji chcemy pobrać |
Wskazówka Możesz pominąć year
i month
, aby otrzymać ostatnią zanotowaną pozycję.
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "konto bankowe": { "20140710": 41 }, "karta kredytowa": { "20140711": 6 } }, "domena2.test.pl": { "dobry dermatolog krak\u00f3w": { "20140711": 1 }, "dobry dermatolog": { "20140710": 9 } } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty strukturze fraza:historia
, gdzie historia jest zbiorem dzień:wartość
:
Nazwa | Opis |
---|---|
dzień | Dzień w formacie YYYYMMDD |
wartość | Pozycja na której została wykryta monitorowana fraza lub null jeśli nie ma danych z dnia albo nie znaleziono frazy w wynikach |
Wygenerowanie raportu pozycji dla kampanii.
Uwaga Jeśli kampania nie istniała w podanym miesiącu, zostanie zwrócony błąd 1006
ze wskazaniem na błędne kolumny year,month
.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=pdf&campaign=domena1.test.pl&year=2016&month=2
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
campaign | Nazwa kampanii |
year | Rok dla którego ma być wygenerowany raport |
month | Miesiąc |
Odpowiedź
{ "status": 1, "data": { "expiration": 1487942936, "file": "https:\/\/app.webmity.com\/temporary\/campaign_report\/00000001-0000000002\/domain1.pl-luty-2016-a1b2c3.pdf" } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
expiration | Integer | Czas na pobranie pliku PDF w postaci znacznika czasowego UNIXTIMESTAMP , po którym zostanie usunięty. Zazwyczaj będzie to 24 godziny. |
file | String | Bezpośredni adres pliku PDF. |
Moduł statyczny. Zawiera akcje pozwalające na odczyt liczby odwiedzin/odsłon domen jak i konkretnych artykułów.
Pobiera statystyki odwiedzin i odsłon danej domeny/domen.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=stats&action=visits&year=2014&month=7&day=28&domains=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domains | Nazwy domen rozdzielone średnikiem (; ) lub pojedyncza domena |
year | Rok którego statystyki chcemy otrzymać |
month | Miesiąc którego statystyki chcemy otrzymać |
day opcjonalne |
Dzień którego statystyki chcemy otrzymać |
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "20140728": { "pages": 427, "visits": 311 } }, "domena2.test.pl": { "20140728": { "pages": 1027, "visits": 783 } } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:
Nazwa indeksu | Typ | Opis |
---|---|---|
pages | Integer | Ilość odsłon wygenerowana przez unikalnych użytkowników |
visits | Integer | Ilość unikalnych wizyt użytkowników |
Moduł zawiera zestaw akcji pozwalających na zarządzanie zleceniami działu copywritingu. Samo działanie modułu zostało przedstawione w artykule pomocy.
Zalecany sposób implementacji modułu:
Pobranie listy katalogów.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=folders
Odpowiedź
{ "status": 1, "data": [ { "folder": 2, "name": "Artyku\u0142y o samochodach", "domain": "domena1.test.pl", "lastaction": 1458855167, "total": 12, "finished": 7, "unused": 2, "pendingai": 3, "pendinghuman": 2 }, { "folder": 5, "name": "Opisy produkt\u00f3w", "domain": null, "lastaction": 1637162834, "total": 5, "finished": 3, "unused": 1, "pendingai": 2, "pendinghuman": 0 } ] }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
folder | Integer | Identyfikator folderu w sysytemie |
name | String | Nazwa folderu |
domain | String or Null | Nazwa przypisanej domeny |
lastaction | Integer | Czas ostatniej aktywności w folderze w postaci znacznika czasowego UNIXTIMESTAMP |
total | Integer | Liczba wszystkich zleceń |
finished | Integer | Liczba zakończonych zleceń |
unused | Integer | Liczba nieużytych zleceń |
pendingai | Integer | Liczba zleceń w realizacji (AI) |
pendinghuman | Integer | Liczba zleceń w realizacji (człowiek) |
Pobieranie listy zleceń
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=list&folder=4&status=done
Dodatkowe parametry:
Nazwa indeksu | Typ | Opis |
---|---|---|
folder | Integer | Identyfikator folderu |
id opcjonalne |
String | Identyfikatory zleceń rozdzielone średnikiem |
status opcjonalne |
Enum | Filtruj status zlecenia: pending , done lub used |
premium opcjonalne |
Boolean | Filtruj zlecenia premium |
text opcjonalne |
Boolean | Pokaż zrealizowany tekst. Domyślnie false Uwaga Ustawienie tego parametru ograniczy ilość zwróconych rekordów do 25. Opcji nie należy używać przy sprawdzaniu stanu zleceń. |
Odpowiedź
{ "status": 1, "data": [ { "id": 12, "created": 1471007589, "received": 1471008855, "length": 300, "cost": 9, "who": "ai", "quality": "standard", "status": "done" }, { "id": 30, "created": 1471007601, "received": 1471008863, "length": 300, "cost": 12, "who": "human", "quality": "premium", "status": "done" } ] }
Odpowiedź zawiera tablicę obiektów:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator zlecenia |
created | IntegerUNIXTIMESTAMP |
Czas wysłania zlecenia |
received | Integer lub nullUNIXTIMESTAMP |
Czas otrzymania gotowego tekstu. |
length | Integer | Oczekiwana długość tekstu |
cost | Integer | Koszt zlecenia |
premium | Boolean | Zlecenie w jakości premium |
status | String | Status zlecenia: pending - w realizacji, done - wykonane, used - tekst wykorzystany |
Dla text=true |
||
title | String lub Null | Tytuł sparafrazowanego tekstu |
text | String lub Null | Gotowy tekst |
Zlecenie nowego tekstu do parafrazy lub streszczenia. Poprawnie wykonana akcja spowoduje pobranie środków z konta. W przypadku braku wystarczających środków na koncie, zostanie zwrócony błąd 2003
.
Uwaga Zlecenia trafiają do copywriterów nie związanych bezpośrednio z panelem Webmity, prosimy wykonywać testy z użyciem zapytania text/cost
, które ma takie same parametry lub wybierając potrzebne teksty w ostatecznych testach. Pozwoli to uniknąć niepotrzebnych nieporozumień.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=order&folder=3&type=create&length=short&lang=en&keywords=buying%20car;guide
Dodatkowe parametry:
Nazwa indeksu | Typ | Opis |
---|---|---|
folder | Integer | Identyfikator folderu |
type | Enum | Typ zlecenia: rewrite - parafraza, create - nowy tekst |
who | Enum | Zleceniobiorca: human - zlecenie standardowe, humanpremium - zlecenia wysokiej jakości, ai - zlecenia maszynowe |
copies opcjonalne |
Integer | Liczba kopii, liczba od 1 do 10, domyślnie 1 |
length | Integer | Dla who=human/humanpremium . Docelowa długość tekstu, minimalnie 300, maksymalnie 10000, liczba podzielna przez 100. |
length | Enum | Dla who=ai i type=create . Docelowa długość tekstu: veryshort - 300 znaków, short - 1500 znaków, medium - 3000 znaków lub long - 4500 znaków. |
lang | Enum | Dla who=ai . Język parafrazy: en , cz , fr , es , nl , de , pl , ru , ro lub it . |
keywords | String | Dla who=ai i type=create . Słowa kluczowe lub frazy rozdzielone średnikiem (1 główne oraz do 3 dodatkowych), każda fraza może mieć do 100 znaków, łącznie frazy mogą mieć do 250 znaków. Proszę unikać znaków specjalnych, nazw produktów oraz dwuznacznych słów. |
text | String | Dla type=rewrite . Tekst do parafrazy, minimalnie 300 znaków, maksymalnie 10000 znaków, bez tagów html. |
text | String | Dla who=human/humanpremium i type=create . Opis zlecenia, minimalnie 20 znaków, maksymalnie 10000 znaków, bez tagów html. |
Odpowiedź
{ "status": 1, "data": { "id": [ 20 ], "cost": 110, "count": 1 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Array[Integer] | Identyfikatory zleceń w sysytemie |
cost | Integer | Naliczona kwota EF |
count | Integer | Liczba zleconych tekstów |
Sprawdzenie kosztu zapytania text/order
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=cost&folder=3&type=create&length=short&lang=en&keywords=buying%20car;guide
Dodatkowe parametry:
Nazwa indeksu | Typ | Opis |
---|---|---|
Takie same parametry jak text/order . |
Odpowiedź
{ "status": 1, "data": { "balance": 8950, "cost": 110, "count": 1 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
balance | Integer | Stan konta w EF |
cost | Integer | Koszt zlecenia w EF |
count | Integer | Liczba zleconych tekstów |
Zmiana statusu zlecenia. Zlecenie musi mieć status done
lub used
, nie można też zmienić statusu dla tekstów użytych w panelu.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=list&folder=3&id=1;2;5&status=used
Dodatkowe parametry:
Nazwa indeksu | Typ | Opis |
---|---|---|
folder | Integer | Identyfikator folderu |
id | String | Identyfikatory zleceń rozdzielone średnikiem |
status | Enum | Status do ustawienia: done lub used |
Odpowiedź
{ "status": 1, "data": { "count": 3 } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
count | Integer | Liczba znalezionych zleceń |
changed | Integer | Liczba zaktualizowanych zleceń |
Udostępnia akcje umożliwiające wykonanie eksportu raportów pozycji według następujących kryteriów: domen i czasu.
Wyświetla wszystkie monitorowane słowa kluczowe domeny wraz z aktualnymi pozycjami, opcjonalnie z historią pozycji dla wybranej daty.
Uwaga Jeśli zostanie wybranych kilka wyszukiwarek do monitorowania. Funkcja list może wtedy zwracać pozycje z danego dnia dla przypadkowej wyszukiwarki. Ewentualne zapotrzebowanie na wsparcie wielu wyszukiwarek w API prosimy zgłaszać na adres podany w stopce.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=position&action=list&domains=domena1.test.pl;domena2.test.pl
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domains | Nazwy domen rozdzielone średnikiem (; ) lub pojedyncza domena |
year | Rok z którego raport pozycji chcemy pobrać |
month | Miesiąc z którego raport pozycji chcemy pobrać |
day opcjonalne |
Dzień z którego raport pozycji chcemy pobrać |
Wskazówka Możesz pominąć year
i month
, aby otrzymać ostatnią zanotowaną pozycję.
Odpowiedź
{ "status": 1, "data": { "domena1.test.pl": { "konto bankowe": { "20140710": 41 }, "karta kredytowa": { "20140711": 6 } }, "domena2.test.pl": { "dobry dermatolog krak\u00f3w": { "20140711": 1 }, "dobry dermatolog": { "20140710": 9 } } } }
Odpowiedź w postaci object
, gdzie indeksy to nazwy domen, a wartości zawierają obiekty strukturze fraza:historia
, gdzie historia jest zbiorem dzień:wartość
:
Nazwa | Opis |
---|---|
dzień | Dzień w formacie YYYYMMDD |
wartość | Pozycja na której została wykryta monitorowana fraza lub null jeśli nie ma danych z dnia albo nie znaleziono frazy w wynikach |
Wygenerowanie raportu pozycji dla strony reklamowej.
Uwaga Jeśli strona nie istniała w systemie w podanym miesiącu, zostanie zwrócony błąd 1006
ze wskazaniem na błędne kolumny year,month
.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=position&action=pdf&domain=domena1.test.pl&year=2016&month=2
Dodatkowe parametry:
Nazwa indeksu | Opis |
---|---|
domain | Nazwa domeny |
year | Rok dla którego ma być wygenerowany raport |
month | Miesiąc |
Odpowiedź
{ "status": 1, "data": { "expiration": 1487942936, "file": "https:\/\/app.webmity.com\/temporary\/domain_report\/00000001-0000000002\/domain1.pl-luty-2016-a1b2c3.pdf" } }
Odpowiedź zawiera obiekt:
Nazwa indeksu | Typ | Opis |
---|---|---|
expiration | Integer | Czas na pobranie pliku PDF w postaci znacznika czasowego UNIXTIMESTAMP , po którym zostanie usunięty. Zazwyczaj będzie to 24 godziny. |
file | String | Bezpośredni adres pliku PDF. |
Wyświetla podstawowe informacje o koncie klienta oraz dostępnych dla niego zasobach i limitach.
Wyświetla podstawowe informacje o koncie.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=about
Odpowiedź
{ "status": 1, "data": { "id": 187, "login": "kontotestowe", "name": "Konto testowe", "created": 1377599421, "expiration": null, "balance": 4212 } }
Struktura odpowiedzi:
Nazwa indeksu | Typ | Opis |
---|---|---|
id | Integer | Identyfikator użytkownika |
login | String | Login użytkownika do systemu |
name | String | Nazwa użytkownika |
created | Integer | Znacznik czasowy zawierający datę utworzenia konta |
expiration | Integer lub null | Znacznik czasowy zawierający datę wygaśnięcia konta. Gdy null to konto jest bezterminowe. |
balance | Integer | Saldo punktów przedpłaconych |
Prosta akcja służąca do weryfikacji połączenia.
Przykładowe zapytanie
Żądanie
https://app.webmity.com/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=ping
Odpowiedź
{ "status": 1, "data": { "pong": 1406647280 } }
Struktura odpowiedzi:
Nazwa indeksu | Typ | Opis |
---|---|---|
pong | Integer | Aktualna data serwera w postaci znacznika czasowego UNIXTIMESTAMP |
Uwaga! Publikowane skrypty zostały przetestowane z wykorzystaniem parsera PHP w wersji 5.4
Uniwersalna klasa PHP do połączenia i obsługi żądań API
Wykorzystywana przy pozostałych przykładach.
<?php /** * Wyjątek dla klasy */ class WMApiException extends Exception { public $fromApi = false; function __construct($message, $code = 0, $fromApi = false){ $this->fromApi = $fromApi; parent::__construct($message, $code); } } /** * Przykładowa klasa do połączeń z API Webmity */ class WMApi { private $apikey = null; private $secretkey = null; # czas oczekiwania na odpowiedź public $timeout = 30; public function __construct( $apikey, $secretkey ){ # zapis kluczy $this->apikey = $apikey; $this->secretkey = $secretkey; } public function send( $module, $action, $params = Array(), $files = Array() ){ # łączenie zapytania z kluczami $params = array_merge( (array) $params, Array( 'apikey' => $this->apikey, 'secretkey' => $this->secretkey, 'module' => $module, 'action' => $action, ) ); $curl = curl_init(); # tworzenie QUERY_STRING $encoded_params = http_build_query( $params ); # sprawdzanie długości zapytania (wysłanie przy użyciu GET jest często szybsze) $use_post = ( strlen( $encoded_params ) > 4000 ); # adres API $url = 'https://app.webmity.com/apiv1'; # wysyłka z użyciem GET if(!$use_post) $url .= '?' . $encoded_params; curl_setopt( $curl, CURLOPT_URL, $url ); curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 ); curl_setopt( $curl, CURLOPT_TIMEOUT, $this->timeout ); curl_setopt( $curl, CURLOPT_HEADER, 0 ); # jeśli są wysyłane pliki.. if(count($files)){ # czyszczenie parametrów, jeśli zostały już dodane w QUERY_STRING if( !$use_post ) $params = Array(); # załączanie plików w parametrach foreach($files as $key => $file){ # php 5.5+ if(version_compare(PHP_VERSION, '5.5.0') >= 0){ $params[$key] = new CURLFile($file); # przed php 5.5 } else { $params[$key] = '@'. realpath($file); } } # upload jako multipart curl_setopt( $curl, CURLOPT_POST, 1 ); curl_setopt( $curl, CURLOPT_HTTPHEADER, Array( 'Content-type: multipart/form-data' ) ); curl_setopt( $curl, CURLOPT_POSTFIELDS, $params ); } else { # niezbędne jest ustawienie kilku opcji przy metodzie POST if( $use_post ){ curl_setopt( $curl, CURLOPT_POST, 1 ); curl_setopt( $curl, CURLOPT_HTTPHEADER, Array( 'Content-type: application/x-www-form-urlencoded' ) ); curl_setopt( $curl, CURLOPT_POSTFIELDS, $encoded_params ); } } $response = curl_exec( $curl ); # błąd curl if(curl_errno($curl) > 0) throw new WMApiException( curl_error($curl), curl_errno($curl), false ); curl_close( $curl ); $response = json_decode( $response, true ); # brak odpowiedzi / nieprawidłowy JSON if( !isset( $response['status'] ) ) throw new WMApiException( 'Brak odpowiedzi lub nieprawidłowy JSON.' , 0, false ); # błąd zwrócony przez api if( $response['status'] !== 1 ) throw new WMApiException( "Błąd #{$response['error']}" . ( isset($response['message']) ? ": {$response['message']}" : '' ) , $response['error'] , true); # zwrócenie danych return $response['data']; } }
Przykład użycia klasy do połączenia z API Webmity, wyświetlający domeny wraz z ich aktualnymi zrzutami ekranów.
<?php # klasa do połączeń z api require_once( 'wmapi.class.php' ); # kodowanie strony header('Content-Type: text/html; charset=utf-8'); # utworzenie obiektu $api = new wmapi( '__APIKEY__', '__SECRETKEY__' ); # pobieranie listy domen $domains = $api->send( 'domain', 'list' ); # pobieranie zrzutów stron $screenshot = $api->send( 'domain', 'screenshot', Array( 'domains' => implode( ';', array_keys($domains) ) ) ); # wyświetlenie danych w czytelnej postaci foreach( $domains as $name => $info ){ $created = date( 'r', $info['created'] ); $image = isset( $screenshot[$name]['image'] ) ? "<img src='data:{$screenshot[$name]['mime']};base64,{$screenshot[$name]['image']}' title='{$name}' />" : "<i>Brak zrzutu</i>"; echo " <p> <strong>{$info['name']}</strong><br> Status: {$info['status']}<br> <small>Data utworzenia: {$created}<br></small> {$image} </p> "; }
Przykład wgrania pliku oraz późniejszego użycia go w nowym artykule.
Uwaga Poniższy kod wymaga aktualnej wersji klasy php załączonej powyżej.
<?php # klasa do połączeń z api require_once( 'wmapi.class.php' ); # kodowanie strony header('Content-Type: text/html; charset=utf-8'); # utworzenie obiektu $api = new wmapi( '__APIKEY__', '__SECRETKEY__' ); # wgranie grafiki $file = $api->send( 'file', 'upload', [], ['file' => './banner.png'] ); # dodanie artykułu zawierającego grafikę $api->send( 'article', 'add', [ 'domain'=>'domena.pl', 'name'=>'Artykuł z grafiką', 'title'=>'Artykuł z grafiką', # atrybuty alt oraz style są opcjonalne # jeśli wymiary będą inne niż wybranego pliku, grafika zostanie dopasowana przed eksportem 'text'=>'<p>Oto jest grafika <img alt="" src="'. $file['url'] .'" style="width: 487px; height: 169px;" /></p>' ] ); # eksport danych na stronę reklamową $api->send( 'domain', 'commit', ['domain'=>'domena.pl'] );
Lista zwracanych kodów błedów wraz z legendą.
Numer błędu | Opis |
---|---|
1000 | Brak odpowiedzi (prosimy zgłosić) |
1001 | Brak autoryzacji / Błędne dane |
1002 | Nieznany moduł / Konto nie posiada wystarczających uprawnień |
1003 | Nieznana akcja |
1004 | Brak uprawnień / Ograniczenie klucza API |
1005 | Brak wymaganych parametrów dla wybranej akcji (message zawiera nazwę parametru) |
1006 | Zasób nie istnieje lub konto nie jest jego właścicielem (message zawiera nazwę parametru) |
1007 | Żądanie używa znaków z poza kodowania utf-8 |
2001 | Brak wybranego parametru do edycji |
2002 | Parametr poza zakresem (message zawiera nazwę parametru) |
2003 | Brak wystarczających środków na wykonanie akcji (message zawiera koszt) |
2071 | Plik nie został wysłany |
2072 | Osiągnięto maksymalną liczbę wgranych plików w ciągu 48 godzin |
2073 | Przekroczono dopuszczalny rozmiar pliku |
2074 | Niedozwolony typ pliku |
2075 | Obraz jest zbyt mały |
2076 | Obraz ma nieobsługiwany format lub jest uszkodzony |
2090 | Błąd komunikacji z copywriterami (prosimy zgłosić) |
2099 | Duplikacja treści |
Lista zmian API oraz dokumentacji.
Wersja / data | Opis |
---|---|
v1.11 23 stycznia 2023 |
|
v1.10 10 stycznia 2022 |
|
v1.9 8 grudnia 2021 |
|
v1.8 25 lutego 2020 |
|
v1.7 5 listopada 2018 |
|
v1.6 22 sierpnia 2018 |
|
v1.5 9 października 2017 |
|
v1.4 22 lutego 2017 |
|
v1.3 12 września 2016 |
|
v1.2 20 czerwca 2016 |
|
v1.1 18 kwietnia 2016 |
|
v1.0 5 sierpnia 2014 |
Wprowadzenie API.
|