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).