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.
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!
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"}} |
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"}} |
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}} |
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"]}} |
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"]}} |
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. |
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. |
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.