Getting started ::::::::::::::: Database layout =============== Player ------ The main database table is the table of players. A player instance has the following attributes:: key_name # A string with the player's name as used for sorting, i.e. # "family name" first: "Cho Chikun", "Redmond Michael" sex # Integer, 0 = UNKNOWN, 2 = MALE, 3 = FEMALE, 100 = BOT, 1000 = OTHER date_of_birth # string in the form YYYY-MM-DD, or YYYY-MM, or YYYY date_of_death # string in the form YYYY-MM-DD, or YYYY-MM, or YYYY citizenship # 3-letter string, CHN, JPN, KOR, TWN, ... (ISO 3166-1 alpha-3) affiliation # integer # 0 = UNKNOWN # 1 = CHINESE_WEIQI_ASSOCIATION # 2 = TAIWAN_GO_ASSOCIATION # 3 = NIHON_KIIN # 4 = KANSAI_KIIN # 5 = HOENSHA # 6 = HANGUK_KIWON # 8 = AGA # 9 = EGF # 20 = AMATEUR wikidata # string with a wikidata ID, e.g., "Q18700504" Furthermore, a player can have *names*, *ranks*, and *links*. Names ----- A name instance points to a player, and collects all spellings of a fixed "base name". A player can have several name instances pointing to her/him, in case her/his name changed, e.g., by marriage, or because of a change of name for other reasons. A name instance has the following attributes:: player # the corresponding Player instance goratings # string with a goratings.org ID (or null) valid_from # "valid from" (partial) date valid_to # "valid to" (partial) date typ # type of name, # 0 = UNKNOWN, 1 = BIRTH, 2 = MERRIED, 3 = AKA, 1000 = OTHER standard # True if this is the (currently) preferred name (Simple) Names -------------- A (simple) name has the following attributes:: name # A string with the name, e.g. one of # "Ahn Kukhyun", "An Kuk-hyeong", "安国铉", "안국현", "安国鉉", # "Ahn Kuk-hyun", "安國鉉" playername # The corresponding Name instance databases # a list of databases ("GoGoD", "Go4go", "AEB") which use this # spelling incorrect # Boolean, True if this spelling is "incorrect" (e.g., a spelling # error, or mix-up of different romanization methods) order_reversed # Boolean, True if in this spelling the usual order of the # compoents of the name (family name, given name) is reversed # Typically, this should be applied if the given name comes # first in Asian names languages # A list of languages for which this spelling can be used (plus # a marker if this is the preferred spelling for the given # language) Rank ---- A rank entry has the following attributes:: rank # string, in the form "1p", "2p", ... (pro ranks); "6d", ... (amateur # ranks) valid_from # string denoting the (partial) date at which this rank was # assigned (YYYY-MM-DD, YYYY-MM, or YYYY) player # the corresponding player Links ----- A link entry has the following attributes:: url # string with the full (url-encoded) url, e.g. # "https://en.wikipedia.org/wiki/Akaboshi%20Intetsu" wikipedia # string, containing the wikipedia country code ("en", "fr", # "zh", "ja", ...) if this is a wikipedia link, otherwise empty senseislibrary # Boolean, True if this link points to Sensei's Library affiliation # Boolean, True if this link points to the home organization of # this player player # the corresponding player Detailed Names -------------- **Detailed names are not yet in use.** This database table would allow storing more detailed information about names (validity period, split names up into several components). It uses a very unspecific scheme (i.e., not relating to first/last name, familiy/given name, etc.) which allows to split a name into the "key name" (used for sorting a list of names) and several types of components of names before and after the key name. I learned about this from http://stackoverflow.com/a/9634716 (see also http://www.editeur.org/93/Release-3.0-Downloads/#Specification). Attributes:: playername # The corresponding Name instance titles_before_names # string names_before_key_names # string prefix_to_key_names # string key_name # string names_after_key_names # string suffix_to_key_names # string qualifications_and_honors_after_key_names # string primary # Boolean, True if this is this player's "native name" languages # A list of languages for which this spelling can be used (plus # a marker if this is the preferred spelling for the given # language) Contributing via the web site ============================= ... without an account ---------------------- Visit the web page at https://db.u-go.net/, search for players, go to the player's detail view page by clicking her/his name in the left-most column, and use the ``Send feedback`` link at the bottom of the page. Of course, you can also just send me an email directly at ug@geometry.de. ... with a u-go.net account --------------------------- If you intend to contribute regularly/systematically, email me and I will set up an account for you. (Depending on whether I already "know" you, I might first inquire about your background and or your plans on what to do ...) After logging in at https://db.u-go.net/admin/, you will have ``Edit`` and ``Delete`` links at the bottom of the player detail pages. If appropriate, we could also set up things so that you could use the REST API to add and edit data via scripts. **It is understood that all your edits are placed under a public domain license, and that you have the rights to do so, i.e., that you do not use sources which do not allow such usage (such as copyrighted/protected material), and that you do not claim copyright yourself on the changes you submit.** Accessing the data in scripts ============================= The complete data is available for download in JSON format at https://u-go.net/dbdownload/ (*not yet ... but coming soon*). The data can also be accessed programmatically via a `REST API `_, i.e., by sending requests to the web server and reading the response. You can just point your browser to https://db.u-go.net/playerdb/players/ to get an impression. To make use of the data, you probably want to access it in an automated way. One way to do so is using command line tools. For example, you could retrieve the list of players (including name, rank and link information) using `httpie `_ by:: http https://db.u-go.net/playerdb/players/ You will receive a response in JSON format, at the time of this writing:: HTTP 200 OK Allow: GET, POST, OPTIONS Content-Type: application/json Vary: Accept { "count": 2723, "next": "https://db.u-go.net/playerdb/players/?page=2", "previous": null, "results": [ { "id": 2427, "key_name": "Abe Kamejiro", "sex": "Male", "date_of_birth": "1845", "date_of_death": "1925", "citizenship": "JPN", "affiliation": "Hoensha", "wikidata": null, "names": [ { "player": "https://db.u-go.net/playerdb/players/2427/", "simplenames": [ { "id": 8376, "playername": "https://db.u-go.net/playerdb/names/1/", "name": "Abe Kamejiro", "databases": [ "GoGoD" ], "languages": [ { "language": "en", "preferred": true } ], "incorrect": false, "order_reversed": false }, { "id": 13798, "playername": "https://db.u-go.net/playerdb/names/1/", "name": "阿部亀治郎", "databases": [], "languages": [], "incorrect": false, "order_reversed": false } ], "goratings": null, "valid_from": "", "valid_to": "", "typ": "Unknown", "standard": true } ], "ranks": [ { "id": 4256, "player": "https://db.u-go.net/playerdb/players/2427/", "rank": "6p", "valid_from": "1914" } ], "links": [ { "player": "https://db.u-go.net/playerdb/players/2427/", "url": "http://senseis.xmp.net/?AbeKamejiro", "affiliation": false, "wikipedia": "", "senseislibrary": true } ], "creator": "ug", "last_changed_by": "ug", "added": "2016-12-17T11:30:22.424986Z", "last_changed": "2016-12-18T21:16:49.724294Z" }, { "id": 792, "key_name": "Abe Yoshiki", "sex": "Male", "date_of_birth": "1996-07-17", "date_of_death": "", "citizenship": "JPN", "affiliation": "Kansai Kiin", "wikidata": "Q25252696", "names": [ { "player": "https://db.u-go.net/playerdb/players/792/", "simplenames": [ { "id": 742, "playername": "https://db.u-go.net/playerdb/names/2/", "name": "Abe Yoshiki", "databases": [ "Go4go", "GoGoD" ], "languages": [ { "language": "en", "preferred": true } ], "incorrect": false, "order_reversed": false }, { "id": 1405, "playername": "https://db.u-go.net/playerdb/names/2/", "name": "阿部良希", "databases": [], "languages": [ { "language": "ja", "preferred": true }, { "language": "zh", "preferred": true } ], "incorrect": false, "order_reversed": false } ], "goratings": "1465", "valid_from": "", "valid_to": "", "typ": "Unknown", "standard": true } ], "ranks": [ { "id": 1489, "player": "https://db.u-go.net/playerdb/players/792/", "rank": "1p", "valid_from": "2013-07-01" } ], "links": [ { "player": "https://db.u-go.net/playerdb/players/792/", "url": "http://kansaikiin.jp/kisi_prof/abeyoshiki.html", "affiliation": true, "wikipedia": "", "senseislibrary": false } ], "creator": "ug", "last_changed_by": "ug", "added": "2016-12-10T13:48:54.101534Z", "last_changed": "2016-12-17T11:30:26.962502Z" }, { "id": 932, "key_name": "Abe Yoshiteru", "sex": "Male", "date_of_birth": "1941-09-28", "date_of_death": "2009-10-25", "citizenship": "JPN", "affiliation": "Nihon Kiin", "wikidata": "Q3489158", "names": [ { "player": "https://db.u-go.net/playerdb/players/932/", "simplenames": [ { "id": 883, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "Abe Yoshiteru", "databases": [ "AEB", "Go4go", "GoGoD" ], "languages": [ { "language": "en", "preferred": true }, { "language": "sv", "preferred": true } ], "incorrect": false, "order_reversed": false }, { "id": 882, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "安倍吉輝", "databases": [], "languages": [ { "language": "ja", "preferred": true } ], "incorrect": false, "order_reversed": false }, { "id": 4852, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "安倍吉辉", "databases": [], "languages": [ { "language": "zh", "preferred": true } ], "incorrect": false, "order_reversed": false }, { "id": 4853, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "阿部吉辉", "databases": [], "languages": [], "incorrect": false, "order_reversed": false }, { "id": 2350, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "Jošiteru Abe", "databases": [], "languages": [ { "language": "cs", "preferred": false } ], "incorrect": false, "order_reversed": true }, { "id": 2349, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "Yoshiteru Abe", "databases": [], "languages": [ { "language": "cs", "preferred": false }, { "language": "en", "preferred": false } ], "incorrect": false, "order_reversed": true }, { "id": 4287, "playername": "https://db.u-go.net/playerdb/names/3/", "name": "Ёситэру Абэ", "databases": [], "languages": [ { "language": "ru", "preferred": true } ], "incorrect": false, "order_reversed": true } ], "goratings": "142", "valid_from": "", "valid_to": "", "typ": "Unknown", "standard": true } ], "ranks": [ { "id": 25, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "1p", "valid_from": "1960" }, { "id": 26, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "2p", "valid_from": "1961" }, { "id": 27, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "3p", "valid_from": "1962" }, { "id": 28, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "4p", "valid_from": "1963" }, { "id": 29, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "5p", "valid_from": "1964" }, { "id": 30, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "6p", "valid_from": "1966" }, { "id": 31, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "7p", "valid_from": "1970-09-18" }, { "id": 32, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "8p", "valid_from": "1974" }, { "id": 33, "player": "https://db.u-go.net/playerdb/players/932/", "rank": "9p", "valid_from": "1986-11-07" } ], "links": [ { "player": "https://db.u-go.net/playerdb/players/932/", "url": "http://www.nihonkiin.or.jp/player/htm/ki000032.htm", "affiliation": true, "wikipedia": "", "senseislibrary": false }, { "player": "https://db.u-go.net/playerdb/players/932/", "url": "http://senseis.xmp.net/?AbeYoshiteru", "affiliation": false, "wikipedia": "", "senseislibrary": true }, { "player": "https://db.u-go.net/playerdb/players/932/", "url": "https://sv.wikipedia.org/wiki/Abe%20Yoshiteru", "affiliation": false, "wikipedia": "sv", "senseislibrary": false }, { "player": "https://db.u-go.net/playerdb/players/932/", "url": "https://ja.wikipedia.org/wiki/%E5%AE%89%E5%80%8D%E5%90%89%E8%BC%9D", "affiliation": false, "wikipedia": "ja", "senseislibrary": false }, { "player": "https://db.u-go.net/playerdb/players/932/", "url": "https://en.wikipedia.org/wiki/Yoshiteru%20Abe", "affiliation": false, "wikipedia": "en", "senseislibrary": false }, { "player": "https://db.u-go.net/playerdb/players/932/", "url": "https://cs.wikipedia.org/wiki/Jo%C5%A1iteru%20Abe", "affiliation": false, "wikipedia": "cs", "senseislibrary": false } ], "creator": "ug", "last_changed_by": "ug", "added": "2016-12-10T20:30:18.227082Z", "last_changed": "2017-01-16T21:04:25.873975Z" }, # ... and so on This is the first page (i.e., the first 10 entries) of the list of all players. To get the next page, use:: http https://db.u-go.net/playerdb/players/?page=2 (see the "previous" and "next" items in the top-level dictionary), and so on. You can also search the database, for an exact match of a name:: http https://db.u-go.net/playerdb/players/\?searchname\=Go%20Seigen or for a goratings ID:: http https://db.u-go.net/playerdb/players/\?searchgoratings\=123 or for a wikidata ID:: http https://db.u-go.net/playerdb/players/\?searchwikidata\=Q18700504 or for the occurrence of a string in a name or the key_name:: http https://db.u-go.net/playerdb/players/\?search\=Seigen With the ``curl`` command line tool, you can access the API in a similar way. Usually it will be simpler to access the API from a script rather than from the command line. I will illustrate this using the Python requests module:: # -*- coding: utf8 -*- # define the encoding used in the source code if you deal with non-ASCII # strings import json import requests # Retrieve list of players: r = requests.get('https://db.u-go.net/playerdb/players/') data = json.loads(r.content) # data is a Python dictionary containing the answer to our request, # e.g., # data['count'] is the number of entries matching the request # data['results'] is a list of the first 10 entries, each given as # a dictionary # Check out an individual player: r = requests.get('https://db.u-go.net/playerdb/players/185/') data = json.loads(r.content) # data['id'] == 185 # data['key_name'] == 'Hane Naoki' # ... # data['names']: a list of dictionaries # Search for name (exact match), goratings ID, wikidata ID: name = 'Hane Naoki' r = requests.get('https://db.u-go.net/playerdb/players/?searchname=%s' % name) data = json.loads(r.content) goratings = 185 r = requests.get( 'https://db.u-go.net/playerdb/players/?searchgoratings=%d' % goratings) data = json.loads(r.content) wikidata = 'Q18700504' r = requests.get( 'https://db.u-go.net/playerdb/players/?searchwikidata=%s' % wikidata) data = json.loads(r.content) # Search for string contained in a name or key_name: s = 'Naoki' r = requests.get( 'https://db.u-go.net/playerdb/players/?search=%s' % s) data = json.loads(r.content) There is an automatically created overview at https://db.u-go.net/playerdb/apidocs/. Database version ---------------- It could be necessary to change the database layout at some point. The URL https://db.u-go.net/ will always point at the current version. In case you want to use the API programmatically, you might want to include a version number; the current version is available at https://dbv1.u-go.net/ (and will stay available for some time when an update should occur; probably no updates to the data will be made to other versions than the newest).