Introducing MetaKGS.org (for developers/programmers)

anazawa · #1

I'm working on an web app which provides JSON representation of KGS resources.
This app allows you to create a third-party application using KGS resources which includes:

- KGS Game Archives
- KGS Top 100 Players
- KGS Tournaments

You can request a KGS resource you want by using HTTP user agents including client-side Javascript.
While it's unofficial, I've already reported the domain (metakgs.org) and the app to KGS admins.

Home: http://metakgs.org/
Documentation: http://metakgs.org/docs
APIs Explorer: http://metakgs.org/explorer
Repository: https://github.com/anazawa/metakgs.org
Server Status: http://blog.metakgs.org/
(my personal) Ruby Client for MetaKGS: https://github.com/anazawa/metakgs.rb

I hope this app help you create your own tiny application related to KGS

Update: add "Server Status"

Uberdude · #2

Nice idea. One thing I've often wanted from KGS (which old OGS had, and nova OGS sort-of does) is an easy way to see all game between two named players plus number of wins/loses. Could your API makes this available, or would that require too much processing as you'd need to download the entire game history for one player and search through for the other, thus getting banned from the archives for over-use?

TegaiS · #3

Did you try http://kgs.gosquares.net?

Uberdude · #4

Yeah, that's probably as good as you can get given the information KGS makes available. The problem is you need to manually go through 120 months if I want to know all the times I played someone in the last 10 years which is rather a chore.

anazawa · #5

@Underdude

Thanks for your suggestion.

That's not recommended but theoretically possible.
120 API calls make 120 HTTP requests to KGS if the response is not cached.
Since MetaKGS sets a delay between requests to KGS (1 sec/req),
the service would be unavailable for 120 seconds at least.

However, a game record older than 6 months old will be cached by MetaKGS forever,
and so the search result would be immediately returned if your game records
were frequently searched by other users. It depends on your luck

If you really need all the game records, you should set a proper delay
between API calls. Sharing HTTP responses from KGS is the most important thing.

Uberdude · #6

anazawa wrote:

Sharing HTTP responses from KGS is the most important thing.

Does MetaKGS build up a giant lazy-instantiated cache of KGS data?

anazawa · #7

Uberdude wrote:

anazawa wrote:

Sharing HTTP responses from KGS is the most important thing.

Does MetaKGS build up a giant lazy-instantiated cache of KGS data?

Exactly. Just a proxy server which also converts HTML to JSON.

anazawa · #8

TegaiS wrote:

Did you try http://kgs.gosquares.net?

Yes, I did. While I think KGS Analytics is a nice web app,
it seems not maintained anymore but continues to forward HTTP requests
from the users to KGS. I heard tha app sometimes overloads the KGS server.
That's why I wrote MetaKGS.org, well-maintained version of KGS Analytics.

Stefany93 · #9

anazawa wrote:

I'm working on an web app which provides JSON representation of KGS resources.
This app allows you to create a third-party application using KGS resources which includes:

- KGS Game Archives
- KGS Top 100 Players
- KGS Tournaments

You can request a KGS resource you want by using HTTP user agents including client-side Javascript.
While it's unofficial, I've already reported the domain (metakgs.org) and the app to KGS admins.

Home: http://metakgs.org/
Documentation: http://metakgs.org/docs
APIs Explorer: http://metakgs.org/explorer
Repository: https://github.com/anazawa/metakgs.org
Server Status: http://blog.metakgs.org/
(my personal) Ruby Client for MetaKGS: https://github.com/anazawa/metakgs.rb

I hope this app help you create your own tiny application related to KGS

Update: add "Server Status"

So... If I understand correctly, this is a KGS API that allows you to write plugins for KGS?

quantumf · **#10**

Stefany93 wrote:

anazawa wrote:

I'm working on an web app which provides JSON representation of KGS resources.

So... If I understand correctly, this is a KGS API that allows you to write plugins for KGS?

Depends what you mean by a plugin. The KGS GUI doesn't offer any extension points so you can't extend the GUI directly with plugins, like, say, you can do with Chrome. What might be possible* is to build a JavaScript/HTML web page as a container for the KGS Applet, and you can put whatever you want on that container. So it would extend the GUI, but it would be outside the GUI. How well these would work together is debatable.

*Knowing what I know of Java and Applets and security, I suspect the applet is tightly coupled to the domain it's running on, so what I suggested is probably impossible in reality.

Stefany93 · **#11**

quantumf wrote:

Stefany93 wrote:

anazawa wrote:

I'm working on an web app which provides JSON representation of KGS resources.

So... If I understand correctly, this is a KGS API that allows you to write plugins for KGS?

Depends what you mean by a plugin. The KGS GUI doesn't offer any extension points so you can't extend the GUI directly with plugins, like, say, you can do with Chrome. What might be possible* is to build a JavaScript/HTML web page as a container for the KGS Applet, and you can put whatever you want on that container. So it would extend the GUI, but it would be outside the GUI. How well these would work together is debatable.

*Knowing what I know of Java and Applets and security, I suspect the applet is tightly coupled to the domain it's running on, so what I suggested is probably impossible in reality.

Thanks for the explanation...

If it is impossible then what can we use it for :scratch:

quantumf · **#12**

Stefany93 wrote:

Thanks for the explanation...

If it is impossible then what can we use it for :scratch:

You can build a website that shows some stats about KGS players. Whether you should or why you would are questions you or others will have to answer.

Stefany93 · **#13**

quantumf wrote:

Stefany93 wrote:

Thanks for the explanation...

If it is impossible then what can we use it for :scratch:

You can build a website that shows some stats about KGS players. Whether you should or why you would are questions you or others will have to answer.

Oh, super nice. I can write an script with it to put a chart or something on my portfolio...

anazawa · **#14**

Stefany93 wrote:

quantumf wrote:

Stefany93 wrote:

Thanks for the explanation...

If it is impossible then what can we use it for :scratch:

You can build a website that shows some stats about KGS players. Whether you should or why you would are questions you or others will have to answer.

Oh, super nice. I can write an script with it to put a chart or something on my portfolio...

Thanks for your comment. That's one of expected ways to use the API, writing your own tiny application related to KGS.
All you can do is to get some resources from KGS *web* server, such as a list of games played by you, and do something with the data.
You can neither write a plugin to extend the KGS GUI client nor log in to KGS using the API.
MetaKGS API is read-only. It's just a set of methods which simply returns the requested resource.
(quantumf's explanation is very helpful. Thanks)

Javascript example:

Code:

  // using jQuery
  $.getJSON('http://metakgs.org/api/archives/YourAccount', function (data) {
    var games = data.content.games; // => Array containing game objects

    for ( var i = 0; i < games.length; i++ ) {
      var game = games[i];

      game.type;       // => "Ranked"
      game.sgf_url;    // => "http://files.gokgs.com/.../foo-bar.sgf"
      game.board_size; // => 19
      game.handicap;   // => 4
      game.started_at; // => "2015-02-04T12:34Z"
      game.result;     // => "B+Resign"

      game.black;         // => Array containing player objects whose length equals to 1 (2 for rengo games)
      game.black[0].name; // => "foo"
      game.black[0].rank; // => "2k"

      ...
    }

    data.link.prev; // => link to previous month
    data.link.next; // => link to next month
    ...

  });

Unsolved problems:

- SGF files can not be read by client-side Javascript due to the same-origin policy, and so you can neither parse the SGF nor replay the game on web browsers.
- MetaKGS API is quite fragile since it depends on the HTML structure of the KGS web server, while I'm checking the update on Travis CI once a day

Feel free to ask about any unclear points here or on GitHub issues.
Have fun with MetaKGS API!

Update: I visited your website (cool) and found your WordPress plugins. I believe you can write a WordPress plugin related to KGS using MetaKGS API, such as a calendar widget which includes win/lose count per day.

Introducing MetaKGS.org (for developers/programmers)

Who is online