Dokumentacja API

Baza Szedoka udostępnia eksperymentalny interfejs programistyczny, którego można użyć do eksportu/importu danych i tworzenia własnych narzędzi. Poniżej znajduje się dokumentacja tego interfejsu.

Przypominamy, że regulamin Plemion zakazuje użytkowania skryptów niezaakceptowanych przez obsługę gry! Interfejs został zaprojektowany przede wszystkim do użycia w zewnętrznych narzędziach, bądź w programach do analizy danych. Jeżeli zamierzasz użyć API Bazy Szedoka do utworzenia skryptu do gry, będzie on musiał przejść proces akceptacji. Szedok nie ponosi odpowiedzialności za blokady kont spowodowane użytkowaniem nielegalnych skryptów.

Dostałeś/aś kiedyś jakiś skrypt podpisany jako "ode mnie", a teraz już nie działa i chcesz żebym to naprawił? Ludzie to okropne zwierzęta. Dowiedz się więcej na ten temat.

Powrót do indeksu

Podstawowe informacje

API Bazy Szedoka wykorzystuje architekturę REST. Aktualna wersja API to wersja v2. Adres URL API to: https://<ADRES INSTANCJI>/api/v2/. Nasze serwery obsługują HTTP/2 jeśli chcesz go użyć. Nasze API ma ustawione poprawne nagłówki CORS pozwalające na dostęp z każdej domeny.

Wersja API v1 nie jest już wspierana, ale można ją aktywować na żądanie klienta kontaktując się z Szedokiem. Weź jednak pod uwagę, że użycie API v1 wiąże się z istotnymi problemami z bezpieczeństwem. Dokumentacja API v1 nie jest dostępna.

Żądania i odpowiedzi są wysyłane w formacie JSON. Każde żądanie spowoduje zwrócenie obiektu o następującej strukturze:

ok * Czy żądanie się powiodło. Wartość true jeżeli nie wystąpiły problemy, false w przeciwnym wypadku.
code * Kod błędu. 0 jeżeli żaden błąd nie wystąpił, inna wartość w przeciwnym wypadku.
msg * Tekstowy opis błędu. "Sukces" jeżeli żaden błąd nie wystąpił.
ver * Wersja Bazy Szedoka, która wygenerowała tę odpowiedź, np. "v1.0.0".
data * Rezultat żądania, zależny od wywoływanego punktu końcowego. null jeśli żądanie się nie powiodło.

Każde poprawnie sformułowane żądanie zwróci kod odpowiedzi HTTP 200 - inne kody odpowiedzi sygnalizują problem techniczny. Pozwala to na odróżnienie błędów logicznych (np. nieistniejące wioski) od technicznych (np. awaria serwera). W celu obsługi błędów zalecamy korzystanie z parametrów ok oraz code, a także z dodatkowych mechanizmów oferowanych przez konkretne typy żądań.

Gwiazdką zaznaczone są parametry obowiązkowe. Przy zapisie (tj. przy użyciu w żądaniach) ich obecność jest wymagana. Przy odczycie (tj. przy użyciu w odpowiedziach) ich obecność w odpowiedzi jest gwarantowana. Jeżeli parametru nie oznaczono gwiazdką, oznacza to jego częściową lub całkowitą opcjonalność.

Ze względu na wewnętrzną konstrukcję niektórych struktur danych, w odpowiedziach mogą czasem pojawiać się nieudokumentowane parametry. Nie gwarantujemy ich obecności w przyszłych wersjach API, więc nie używaj ich!

POST api_login.php

Punkt końcowy do uwierzytelniania użytkowników. Tutaj otrzymasz token, którego użyjesz w następnych żądaniach. Tokeny wygasają po 15 minutach.

Parametry żądania
username * Nazwa użytkownika
password * Hasło
Parametry odpowiedzi
token * Token autoryzacyjny. Podaj go w następnych żądaniach, aby dokonywać akcji w imieniu użytkownika.
user * Nazwa użytkownika, który został zalogowany.
Przykładowe pomyślne żądanie i odpowiedź
POST /afb14923bfa7c3b7/api/v2/api_login.php HTTP/1.1
Host: s1.plemsy.gorsky.eu
Content-Type: application/json
Connection: close
Content-Length: 39

{"username":"admin", "password":"test"}
HTTP/2 200 OK
Server: nginx
Date: Sun, 27 Oct 2024 21:32:53 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With

{"ok":true,"msg":"Sukces","ver":"v1.0.5","data":{"token":"0ca9e81d4cc21933f62727c8ff7038a6c0e2715eb6c67fc3220851fbd2ad96a2-1730064773-1","user":"admin"}}

POST api_refresh.php

Przedłuża czas ważności poprawnego tokenu autoryzującego otrzymanego przez api_login.php.

Parametry żądania
token * Token autoryzacyjny
Parametry odpowiedzi
token * Token autoryzacyjny z przedłużoną ważnością.
Przykładowe pomyślne żądanie i odpowiedź
POST /afb14923bfa7c3b7/api/v2/api_refresh.php HTTP/1.1
Host: s1.plemsy.gorsky.eu
Content-Type: application/json
Connection: close
Content-Length: 90

{"token": "cde489663cd6fd1931c1cb017c502be1a6abea783d86b616e217087a8001d7c9-1730064774-1"}
HTTP/2 200 OK
Server: nginx
Date: Sun, 27 Oct 2024 21:32:53 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With

{"ok":true,"msg":"Sukces","ver":"v1.0.5","data":{"token":"e51850493853b85a1213e055c98e960f9aeabc2d1631d4657320ebbdbef42f1b-1730064824-1"}}

POST api_check_village.php

Sprawdza dane pojedynczej wioski. W odpowiedzi otrzymasz przewidywany rodzaj wioski, ostatni widziany stan obrony, liczbę wychodzących ataków i liczbę nadchodzących ataków. Możesz uzyskać więcej informacji umieszczając dodatkowe parametry w żądaniu.

Parametry żądania
token * Token autoryzacyjny
coords * Koordynaty wioski do sprawdzenia jako ciąg znaków - mogą być w formacie prostym, np. "123|456", bądź z dekoracjami, np. "Cień Człowieka (336|456) K43".
listOutgoingAttacks Opcjonalnie. Jeżeli ten parametr jest równy true, w odpowiedzi zostanie dodatkowo zwrócona lista ataków wychodzących z wioski.
listIncomingAttacks Opcjonalnie. Jeżeli ten parametr jest równy true, w odpowiedzi zostanie dodatkowo zwrócona lista ataków nadchodzących na tę wioskę.
listAllReports Opcjonalnie. Jeżeli ten parametr jest równy true, w odpowiedzi zostanie dodatkowo zwrócona lista wszystkich raportów dotyczących tej wioski.
listExtraInformation Opcjonalnie. Jeżeli ten parametr jest równy true, w odpowiedzi zostanie dodatkowo zwrócony zestaw wewnętrznych wartości używanych do analiz ataków.
Parametry odpowiedzi
prediction * Przewidywany typ wioski. Może przyjmować wartości: "OFF", "DEFF", "OFF_MAYBE", "DEFF_MAYBE", "UNK".
lastReport * Ostatni raport przedstawiający obronę wioski, w formacie opisanym w sekcji Format raportu; null jeśli nie ma raportu spełniającego kryteria
outgoingAttacks * Liczba ataków wychodzących z tej wioski.
incomingAttacks * Liczba ataków nadchodzących na tę wioskę.
outgoingAttackList Lista ataków wychodzących z wioski, obecna w odpowiedzi jedynie gdy podano parametr listOutgoingAttacks. Format pojedynczego ataku opisano w sekcji Format ataku.
incomingAttackList Lista ataków nadchodzących na wioskę, obecna w odpowiedzi jedynie gdy podano parametr listIncomingAttacks. Format pojedynczego ataku opisano w sekcji Format ataku.
reportList Lista raportów dotyczących wioski, obecna w odpowiedzi jedynie gdy podano parametr listAllReports. Format pojedynczego raportu opisano w sekcji Format raportu.
extraInformation Obiekt zawierający informacje o wewnętrznych parametrach używanych do analizy ataków, obecny w odpowiedzi jedynie gdy podano parametr listExtraInformation. Dostępne informacje podane są poniżej.
Format danych w obiekcie extraInformation
expectedOffPercent Procent offa który może się znajdować w wiosce, na podstawie aktualnego czasu i ostatnio poniesionych strat (wartość zmiennoprzecinkowa od 0 do 100)
reportLifetime Liczba dni które minęły od otrzymania raportu (wartość zmiennoprzecinkowa większa od 0). Równa 0 jeśli wioska w międzyczasie zmieniła właściciela.
expectedReturnTime Oczekiwany najwcześniejszy czas powrotu wojsk atakującego, na podstawie czasu otrzymania raportu i odległości między wioskami. Równy 0 jeśli brak informacji.
predictionReportId Wewnętrzne ID raportu (reportId), który zadecydował o przewidywanym typie tej wioski; 0 jeśli brak.
predictionReasoning Tekstowy opis przyczyny zakwalifikowania wioski do określonego typu, do odczytu przez człowieka.
Przykładowe pomyślne żądanie i odpowiedź
POST /afb14923bfa7c3b7/api/v2/api_check_village.php HTTP/1.1
Host: s1.plemsy.gorsky.eu
Content-Type: application/json
Connection: close
Content-Length: 109

{"token": "383222783f66306956fcac252a48c6fdda1fafc80c9220d787528f23350ab287-1730068536-1", "coords": "515|525"}
HTTP/2 200 OK
Server: nginx
Date: Sun, 27 Oct 2024 21:32:53 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With

{"ok":true,"msg":"Sukces","ver":"v1.0.5","data":{"prediction":"OFF","lastReport":{"time":1625283032,"attUnits":[0,0,0,10,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"defUnits":[0,0,6022,0,2888,0,300,140,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"defAway":[0,0,0,0,0,0,0,0,0,0],"attName":"Kamil9191","attFrom":"048 (336|456) K43 ","defName":"-Misolek-","defFrom":"Taran (515|525) K55 ","timeFormatted":"10 dni 19 godzin temu","reportId":133524099,"uploader":"Tybilla"},"outgoingAttacks":0}}

POST api_save_attacks.php

Dodaje nowe ataki do bazy.

Parametry żądania
token * Token autoryzacyjny
attacks * Lista ataków w formacie wyszczególnionym w sekcji Format ataku.
Parametry odpowiedzi
numSaved * Liczba ataków, które zostały zapisane. Jeżeli ta liczba nie jest równa liczbie ataków w wysłanej liście, to przy zapisie któregoś z nich wystąpił błąd.
status * Lista statusów przetwarzania poszczególnych ataków. Każdy z elementów jest ciągiem znaków, reprezentującym status przetwarzania odpowiadającego ataku. Możliwe wartości: "ok", "to_unknown", "from_unknown", "too_many_attacks", "too_many_targets", "no_speed_match".
Przykładowe pomyślne żądanie i odpowiedź
POST /afb14923bfa7c3b7/api/v2/api_save_attacks.php HTTP/1.1
Host: s1.plemsy.gorsky.eu
Content-Type: application/json
Connection: close
Content-Length: 210

{"token": "78bc5cb4ef55e179a95b9b9a58387226f5b1f2f597e77476baa948f0d3a07b18-1730070964-1", "attacks":[
    {"to": "xxx (293|206) K22", "from": "yyy (291|205) K22", "arrival": 1730071493, "type": "attack_small"}
]}
HTTP/2 200 OK
Server: nginx
Date: Sun, 27 Oct 2024 21:32:53 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With

{"ok":true,"msg":"Sukces","ver":"v1.0.5","data":{"numSaved":1,"status":["ok"]}}

POST api_save_reports.php

Dodaje nowe raporty do bazy. Uwaga - dane raportu przesyłane są bezpośrednio i nie ma możliwości ich weryfikacji - nikt nikomu nie broni dodać raportu z ataku przeprowadzonego w 1985 roku z 99999 szlachcicami w obronie, na wioskę która nie istnieje. Jeżeli chcesz, możesz wypełnić bazę śmieciami na własną odpowiedzialność.

Parametry żądania
token * Token autoryzacyjny
reports * Lista raportów w formacie wyszczególnionym w sekcji Format raportu.
Parametry odpowiedzi
numSaved * Liczba raportów, które zostały zapisane. Jeżeli ta liczba nie jest równa liczbie raportów w wysłanej liście, to przy zapisie któregoś z nich wystąpił błąd.
status * Lista statusów przetwarzania poszczególnych raportów. Każdy z elementów jest ciągiem znaków, reprezentującym status przetwarzania odpowiadającego raportu. Możliwe wartości: "ok", "att_unknown", "def_unknown", "too_many_reports".
Przykładowe pomyślne żądanie i odpowiedź
POST /afb14923bfa7c3b7/api/v2/api_save_reports.php HTTP/1.1
Host: s1.plemsy.gorsky.eu
Content-Type: application/json
Connection: close
Content-Length: 501

{"token": "54c15eb52059e316fbe3f93e13a37b8330dfc4db0b425970ba2d02ec7014cffd-1730072044-1", "reports":[
    {
        "time":1710338629,
        "attUnits":[0,0,5380,0,11,1850,100,0,245,47,1,0,0,0,412,0,11,166,7,0,19,4,0,0],
        "defUnits":[1186,816,97,0,300,51,0,0,0,0,2,0,1186,816,97,0,300,51,0,0,0,0,2,0],
        "defAway":[],
        "attName":"ShadowTouch",
        "attFrom":"Cień Człowieka (291|205) K45",
        "defName":"6WhySoSerious9",
        "defFrom":"SPEED (293|206) K45"
    }
]}
HTTP/2 200 OK
Server: nginx
Date: Sun, 27 Oct 2024 21:32:53 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With

{"ok":true,"msg":"Sukces","ver":"v1.0.5","data":{"numSaved":1,"status":["ok"]}}

Format ataku

Poniżej przedstawiono format obiektów odpowiedzialnych za reprezentację pojedynczego ataku w Bazie. Poniższy format jest używany zarówno przy zapisie jak i odczycie.

Format ataku
attackId Unikalny numeryczny identyfikator, który nie zmienia się pomiędzy żądaniami. Użyj go by w szybki sposób rozróżniać od siebie obiekty reprezentujące ataki. Ta wartość jest opcjonalna i ignorowana przy zapisie, lecz jej obecność jest gwarantowana przy odczycie.
from * Koordynaty wioski źródłowej jako ciąg znaków - mogą być w formacie prostym, np. "123|456", bądź z dekoracjami, np. "Cień Człowieka (336|456) K43". Przy odczycie koordynaty będą zawsze podane w formacie prostym.
to * Koordynaty wioski docelowej jako ciąg znaków - mogą być w formacie prostym, np. "123|456", bądź z dekoracjami, np. "Cień Człowieka (336|456) K43". Przy odczycie koordynaty będą zawsze podane w formacie prostym.
arrival * Czas dotarcia ataku w formacie Unixowym, tj. jako liczba sekund które upłynęły od 1 stycznia 1970 roku 00:00:00 UTC.
speed Opcjonalnie - prędkość nadchodzącego ataku w minutach na pole - przykładowo 30 w przypadku taranów, albo 9 dla zwiadu. Przy zapisie możesz nie podawać tej informacji, bądź wpisać tu 0 - prędkość ataku zostanie wtedy wywnioskowana automatycznie na podstawie czasu trwania.
type Opcjonalnie - rodzaj nadchodzącego ataku na podstawie danych o komendach bądź z wieży strażniczej. Może przyjmować wartości "attack", "attack_small", "attack_medium", "attack_large". Możesz nie podawać tej informacji przy zapisie.

Format raportu

Poniżej przedstawiono format obiektów odpowiedzialnych za reprezentację pojedynczego raportu w Bazie. Poniższy format jest używany zarówno przy zapisie jak i odczycie.

Format raportu
reportId Unikalny numeryczny identyfikator, który nie zmienia się pomiędzy żądaniami. Użyj go by w szybki sposób rozróżniać od siebie obiekty reprezentujące raporty. Ta wartość jest opcjonalna i ignorowana przy zapisie, lecz jej obecność jest gwarantowana przy odczycie.
time * Czas otrzymania raportu w formacie Unixowym, tj. jako liczba sekund które upłynęły od 1 stycznia 1970 roku 00:00:00 UTC.
attFrom * Koordynaty wioski atakującej jako ciąg znaków - mogą być w formacie prostym, np. "123|456", bądź z dekoracjami, np. "Cień Człowieka (336|456) K43". Wartość może być pusta (równa pustemu ciągowi) jeżeli raport jest oznaczeniem ręcznym.
attName * Nazwa gracza atakującego, np. "ShadowTouch". Wartość może być pusta (równa pustemu ciągowi) jeżeli raport jest oznaczeniem ręcznym.
defFrom * Koordynaty wioski broniącej jako ciąg znaków - mogą być w formacie prostym, np. "123|456", bądź z dekoracjami, np. "Cień Człowieka (336|456) K43". Wartość może być pusta (równa pustemu ciągowi) jeżeli raport jest oznaczeniem ręcznym.
defName * Nazwa gracza broniącego, np. "ShadowTouch". Wartość może być pusta (równa pustemu ciągowi) jeżeli raport jest oznaczeniem ręcznym.
attUnits * Lista jednostek atakujących. Najpierw należy podać listę jednostek atakujących, w kolejności identycznej jak kolejność jednostek w raportach na danym świecie gry, a zaraz potem w tej samej liście - straty w jednostkach. Lista może być pusta jeżeli raport jest oznaczeniem ręcznym.
defUnits * Lista jednostek broniących, w kolejności identycznej jak kolejność jednostek w raportach na danym świecie gry. Lista może być pusta, jeżeli nie ma informacji o wojskach obrońcy. Najpierw należy podać listę jednostek broniących, a zaraz potem w tej samej liście - straty w jednostkach. Chłopi nie liczą się jako stałe jednostki obronne, więc nie należy podawać ich w tej liście.
defAway * Lista jednostek poza wioską broniącego gracza, w kolejności identycznej jak kolejność jednostek w raportach na danym świecie gry. Lista może być pusta, jeżeli wojska poza wioską nie zostały wykryte.
role Opcjonalnie - jeżeli raport jest odczytywany w ramach sprawdzenia informacji o wiosce (api_check_village.php), ten parametr informuje czy sprawdzana wioska występuje w tym raporcie w roli atakującego czy broniącego. Możliwe wartości: "attacker", "defender", "none". Ten parametr jest ignorowany przy zapisie. Wartość "none" jest zwracana jedynie w przypadku oznaczeń ręcznych i możesz w ten sposób je rozpoznawać.
prediction Opcjonalnie - jeżeli raport jest odczytywany w ramach sprawdzenia informacji o wiosce (api_check_village.php), ten parametr informuje o przewidywanym typie wioski na podstawie tego raportu. Możliwe wartości: "OFF", "DEFF", "OFF_MAYBE", "DEFF_MAYBE", "UNK". Ten parametr jest ignorowany przy zapisie.
uploader Opcjonalnie - nazwa użytkownika, który dodał raport bądź oznaczenie. Ten parametr jest ignorowany przy zapisie. Ten parametr może być nieobecny przy odczycie, np. w wypadku raportów należących do usuniętych użytkowników.

Eksporty danych w formacie CSV

Oprócz API REST oferujemy również kilka prostych punktów końcowych, które pozwalają łatwo odczytać wszystkie zapisane dane za jednym zamachem, w formacie CSV. Przeznaczone są one głównie do szybkiego importu danych np. do Excela, jednakże nikt nikomu nie broni użyć ich w jakimkolwiek innym przeznaczeniu.

Dostęp do danych nie wymaga logowania - wystarczy posiadać odpowiedni link, który możesz znaleźć w zakładce Przeglądaj dane » API. Wyniki żądań są cachowane na serwerze przez 30 minut. Jeżeli link do źródła danych wycieknie do nieupoważnionych osób, możesz unieważnić poprzednie linki.

Powrót do indeksu