家譜開放數(shù)據(jù)接口說明

家譜開放數(shù)據(jù)接口說明

一、綜述

家譜開放數(shù)據(jù)接口目前提供以下兩種形式的數(shù)據(jù)接口。

1.通過訪問資源URI獲取數(shù)據(jù)：根據(jù)標(biāo)準(zhǔn)API接口，通過訪問單個(gè)資源的URI,獲得

該資源的所有RDF三元組（屬性和值）。

2.通過查詢接口獲取特定類型的數(shù)據(jù)：通過特定API接口，獲取"姓氏"、"先祖名

人"、"地點(diǎn)"、"機(jī)構(gòu)"、"朝代"、"書目"的數(shù)據(jù)。（每次最多取得20條數(shù)據(jù)）

3.通過SparqlEndpoint獲取數(shù)據(jù)

注：使用家譜開放數(shù)據(jù)接口時(shí)需要提供APIKey進(jìn)行驗(yàn)證。開發(fā)人員請?jiān)谏虾D書館數(shù)

據(jù)開放平臺(tái)進(jìn)行用戶注冊，并獲取獨(dú)立的APIKey.

注冊網(wǎng)址：

二、接口調(diào)用方式說明

1.通過訪問資源URI獲取數(shù)據(jù)

功能：輸入資源URI,獲取資源的RDF數(shù)據(jù)。如返回結(jié)果數(shù)據(jù)中存在其他資源的

URI時(shí)，可通過該接口獲取其他資源的RDF數(shù)據(jù)。

API接口：［參數(shù)l］&key=［參數(shù)2］

輸入：

［參數(shù)1］：資源URI

［參數(shù)2］:用戶的APIKey

輸出：包含資源及其屬性和值的JSON-LD數(shù)據(jù)

資源類型與URI設(shè)計(jì)規(guī)范：

命名空間

家譜文獻(xiàn)題名/jp/authority/title/

實(shí)例(bfInstance)/jp/resource/instance/

朝代/authority/temporal/

版本類型取值詞表/vocab/edition/

作品(bf:Work)/jp/resource/work/

譜籍地/entity/place/

腌/entity/organization/

單件(bf:Item)/jp/resource/item/

人物/jp/entity/person/

堂號(hào)/jp/authority/titleofancestraltemple/

姓氏/authority/familyname/

例如：

輸入：

uri=

&key=02cdb77b436d4dc383flb64exxxxxxxxx

輸出：

(

"@type":[

L

"label":[

(

"?language":"chf,

“@value":'亶原隙氏家髀

"^language":"chs"z

”@value”:“豐原陳氏家譜”

)

L

"@context":{

"label":""

}

2.通過查詢接口獲取特定類型的數(shù)據(jù)

(1)姓氏

功能：輸入姓氏獲取對(duì)應(yīng)的資源數(shù)據(jù)。數(shù)據(jù)匹配方式為完全匹配。

API接口：［參數(shù)l］?key=［參數(shù)2］

輸入：

［參數(shù)1］：姓氏

［參數(shù)2］:用戶的APIKey

輸出：包含姓氏屬性和值的JSON-LD數(shù)據(jù)

例如：

輸入：K?key=02cdb77b436d4dc383flb64exxxxxxxxx

輸出：

(

"@id":嗎

"@typeH:

"label":(

(

"(Slanguage":"chs",

"@value":"陳"

},

{

"^language":"en",

"@value":"chen"

},

"@language":"cht",

"@value":"竦"

)

"description":"見于《世本》.西漢《急就章》列為漢代常見姓氏之一。春秋時(shí)陳國有陳亢，為孔門弟子,春秋

時(shí)齊國有陳乞，事景公為大夫，乂戰(zhàn)國時(shí)楚國有陳學(xué)良，學(xué)者。漢代有陳平.陽武人，開國元?jiǎng)?。陳氏為中國古?/p>

最常見的六大姓氏（王李張劉陳趙）之一。《中國人名大辭典》收有陳氏1012例.宋《日家姓》列為第010姓。

"@context":{

"description":

"label":""

}

返回屬性說明：

屬性類型說明

value:姓名

language:語言

labelliterial"chs":中文簡體

"cht":中文繁體

"en":英文

descriptionliterial姓氏描述

（2）先祖名人（升級(jí)版）

功能：輸入先祖名人的姓氏，姓名，URI,獲取對(duì)應(yīng)的資源數(shù)據(jù)。

API接口：[參數(shù)1]&[參數(shù)2]&[參數(shù)3]?key=[參數(shù)4]

參數(shù)：姓氏精確查詢、姓名模糊查詢、UR1精確查詢（三個(gè)參數(shù)任選其一）

返回?cái)?shù)據(jù)：

?返回人的所有信息及其兒子的URI（可能有多個(gè)兒子，那么就多個(gè)URI）,如果想知道兒子的詳細(xì)信

息,再輸入兒子的URI作為參數(shù)再次調(diào)用本接口；

?當(dāng)符合條件的為多個(gè)人時(shí)，那么返回所有人的所有信息包括其各自兒子的URI;

?如果符合條件的有100個(gè)人以上，最多返回100個(gè)；

?如果人名相同的有多個(gè)人，則顯示多個(gè)人的詳細(xì)信息。

輸入：

[參數(shù)1]：familyName先祖名人姓氏

[參數(shù)2]:personName先祖名人姓名

[參數(shù)3]:personllri先祖名人URI

輸出：包含先祖名人屬性和值的JSON-LD數(shù)據(jù)（數(shù)組格式，含所有兒子的URI）

例如：

輸入：

輸出：

"?graph":(

"@type":

"label":[

(

"@language":"cht",

"@value":"胡昌翼"

},

(

"@language":"chs",

"@value":"胡昌翼"

)

],

"relatedWork":"",

"roleOfFamily":

"temporal":

"temporalValue":"宋代"，

"familyName":""

},

(

"@type":，

"label":[

(

"@language":"cht",

"@value":"胡昌翼"

},

(

"@language":"chs",

"@value":"胡昌翼"

)

],

"relatedWork":"",

"roleOfFamily":

"familyName":""

},

(

"@type":，

"label":[

(

"@language":"cht",

"@value":"胡昌翼"

},

(

"@language":"chs",

"@value":"胡昌翼"

)

],

"relatedWork":"",

"roleOfFamily":

"familyName":""

},

(

"@type":，

"label":[

"@language":"cht",

"@value":"胡昌翼"

},

(

"(?language":"chs",

”@value":"胡昌翼"

)

L

"courtesyName":"宏速"，

"orderOfSeniority":"十七，

"relatedWork":，

"roleOfFamily":

"temporal":

"temporalValue":"五代彳發(fā)唐”,

"familyName":H"

},

(

"@type":，

"label":[

{

"@language":"cht",

"@value":"胡昌翼"

},

(

"(?language":"chs",

”@value":"胡昌翼"

)

I

"parentOf":(

),

"spouseOf":

"birthday":"天祐甲子三月一日"，

"courtesyName":"宏速"，

"deathday":"宋咸平己亥十月初三”，

"description":"字宏11行十七本大唐昭宗皇帝子母何后以天祐甲子三月一日生公于陜曾朱溫逆遭帝

洛陶兼祖三公乃得公以蜀考水羲善舄子遂憂胡姓=以易登彳笈唐同光乙酉明^選士第故耦舄明^胡氏事^具列停

卒宋咸平己亥十月初三享年九十有六娶江西德典利瞿詹氏享年九十有三生三子公葬婺源木里之^子端夫人葬婺源

高盒浮舟塘焉口山向均戴墓園，

"genealogyName":"昌翼公"，

"generationcharacter":"昌"，

"orderOfSeniority":T,

"relatedWork":

"roleOfFamily":

"familyName":

},

(

"@id":嗎

"@type":

"label":[

(

"(Slanguage":"cht",

"@value":"胡昌翼"

"@language":"chs",

”@value”:"胡昌翼"

)

]，

"relatedWork":"",

"roleOfFamily":"",

"temporal":，

"temporalValue":"天祐元年，

"familyName":""

},

(

"@type":，

"label":[

(

"@language":"cht",

"@value":"胡昌翼"

},

(

"@language":"chs",

"@value":"胡昌翼"

)

],

"relatedWork":

"roleOfFamily":"",

"familyName":""

},

(

"@type":，

"label":[

(

"@language":"chs",

"@value":"胡昌翼"

},

(

"@language":"cht",

"@value":"胡昌翼"

)

],

"courtesyName":"宏造'，

"relatedWork":

"roleOfFamily":"",

"familyName":""

)

L

"@context":{

"label":"",

"temporalValue":

"orderOfSeniority":

"courtesyName":

"roleOfFamily":{

"@type":"@id"

},

"familyName":{

"@type":"@id"

},

"relatedWork":{

"@type":"@id"

"temporal":{

"@type":"@id"

},

"spouseOf:{

"@type":"@id"

"parentOf":{

"@type":"@id"

I

"generationcharacter":

"deathday":

"genealogyName":,n',

"description":

"birthday":"H

返回屬性說明：

屬性類型說明

value:姓名

language:語言

labelliterial**chsM:中文簡體

“cht”:中文繁體

“en”:英文

relatedWorkURI相關(guān)家譜文獻(xiàn)的URI

roleOfFamilyURI角色URI（人在家族中的角色，如始祖、始遷祖等先祖類型。）

familyNameURI姓氏URI

genderliterial性別

familyURI家族URI

childOfURI父親URI

spouseOfURI配偶URI

genealogyNameliterial譜名（人在家譜上記載的譜名。）

courtesyNameliterial字

pseudonymliterial號(hào)

orderOfSeniorityliterial排行

generationcharacterliterial字輩

posthumousTitleliterial啦號(hào)

birthdayliterial生于

deathdayliterial卒于

descriptionliterial人物描述

temporalValueliterial朝代描述

temporalURI朝代URI

parentOfURI兒子URI

(3)地名

功能：輸入地名，獲取對(duì)應(yīng)的資源數(shù)據(jù)。數(shù)據(jù)匹配方式為完全匹配。

API接口：[參數(shù)l]?key=[參數(shù)2]

輸入：

[參數(shù)1]:地名

[參數(shù)2]:用戶的APIKey

輸出：包含地名屬性和值的JSON-LD數(shù)據(jù)(數(shù)組格式)

例如：

輸入：

輸出：

(

"@type":

"label":[

(

"^language":"chs"z

"@value":"杞縣”

},

(

"@language":"cht"z

"@value":"杞㈱，

)

L

"city"："開封市"，

"country"：[

(

"@language":"chs",

“@value":"中國"

},

(

"^language":"cht"z

“@value":"中尉'

)

I

"county":"杞縣，

"province":"河南省",

"sameAs'1:

"@context":{

"country"：

"city":""z

"county":

"sameAs":{

"@type":"@id"

},

"label":

"province":""

返回屬性說明：

屬性類型說明

value:地名(對(duì)應(yīng)"國家"、"省"、"市"、"縣"中的最小行政區(qū)劃)

language:語言

labelliterial"chs":中文簡體

"cht":中文繁體

"en":英文

countryliterial國家

provinceliterial省

cityliterial市

countyliterial縣

sameAsURI經(jīng)緯度URI

descriptionliterial地名描述

(4)機(jī)構(gòu)

功能：輸入機(jī)構(gòu)的簡稱或全稱，獲取對(duì)應(yīng)的資源數(shù)據(jù)。數(shù)據(jù)匹配方式為模糊匹配。

API接口：［參數(shù)l］?key=［參數(shù)2］

輸入：

［參數(shù)1］：機(jī)構(gòu)簡稱/全稱

［參數(shù)2］:用戶的APIKey

輸出：包含機(jī)構(gòu)屬性和值的JSON-LD數(shù)據(jù)(數(shù)組格式)

例如：

輸入：

輸出：

(

"@type":

"label":［

(

"@language":"chs",

"@value":"上海圖書館"

},

(

"@language":"cht",

"@value":"上海圄善解，

"^language":"en",

"@value":"Shanghailibrary"

)

"abbreviateName":[

"(?language":"chs",

"(?value":"上圖"

},

(

"(?language":"cht",

"@value":—

)

1,

"address":{

"@language":"chs",

"@value":”上海市徐匯區(qū)淮海中路1555號(hào)”

},

"region":

"@context":{

"address":「

,,

"abbreviateName:""z

"label":

"region":{

"@type":"@id"

)

}

返回屬性說明：

屬性類型說明

value:機(jī)構(gòu)名稱

language:語言

labelliterial"chs":中文簡體

"cht":中文繁體

"en":英文

labelliterial機(jī)構(gòu)全稱

abbreviateNameliterial機(jī)構(gòu)簡稱

addressliterial地址

regionURI機(jī)構(gòu)所在地URI

(5)朝代

功能：

1.輸入朝代、年號(hào)，獲取朝代起止年數(shù)據(jù)。

2.輸入年號(hào)紀(jì)年，獲取公元年數(shù)據(jù)。

3.輸入公元年，返回朝代紀(jì)年。

4.輸入朝代，返回年號(hào)、帝王、起止年

5.獲取所有朝代

API接口:

［參數(shù)l］json?key=［參數(shù)2］

輸入方式1:

［參數(shù)1］：朝代或朝代年號(hào)。

［參數(shù)2］:用戶的APIKey

輸出：朝代起止年的JSON-LD數(shù)據(jù)（數(shù)組格式）

例如：

輸入：

輸出：

（

"result":{

"data":"1368~1644",

"uri":""

）

}

輸入方式2：

【參數(shù)1］：朝代紀(jì)年。

［參數(shù)2］:用戶的APIKey

輸出：公元年的JSON-LD數(shù)據(jù)（數(shù)組格式）

例如：

輸入：

輸出：

（

"result":{

"data":"1369",

"uri":""

）

}

輸入方式3:

［參數(shù)1］：公元年。

［參數(shù)2］:用戶的APIKey

輸出：朝代紀(jì)年的JSON-LD數(shù)據(jù)（數(shù)組格式）

例如：

輸入：

輸出：

（

"result":{

"data":"明,元至正29年，明2年,明洪武2年”，

"uri":"M

）

}

輸入方式4：

［參數(shù)1］：朝代。

［參數(shù)2］:用戶的APIKey

輸出：朝代紀(jì)年的JSON-LD數(shù)據(jù)（數(shù)組格式）

例如：

輸入：

輸出：

{

"result":[

(

"monarch":

"reignTitle":

"monarchName":

"label":嗦",

"uri":

"dynasty":嗪"，

"end":"-206",

"begin":"-221"

},

(

"monarch'1:"始皇帝"，

"reignTitle":

"monarchName":"威政，

"label":"秦",

"uri":

"dynasty":"秦’

"end":"-210",

"begin":M-221"

I

{

"monarch":"二世，

"reignTitle":

"monarchName":"嬴胡亥",

"label":"秦"，

"uri":

"dynasty":"秦"，

"end":"-207",

"begin":"-209"

},

(

"monarch":

"reignTitle":

"monarchName":"扁子?jì)?,

"label":"秦，

"uri":

"dynasty":"秦，

"end":"-206",

"begin":"-206"

},

(

"monarch":嗎

"reignTitle":"秦興，

"monarchName":"薛舉，

"label":"秦秦興，

"uri":

"dynasty":"秦",

"end":"618",

"begin":"617"

)

]

輸入方式5:

[參數(shù)1]：temporal.json

[參數(shù)2]:用戶的APIKey

輸出：朝代紀(jì)年的JSON-LD數(shù)據(jù)(數(shù)組格式)

例如：

輸入：

輸出：

(

"data"：[

(

"uri":""z

"label":"g",

"end":

"begin":"-1989"

},

(

"uri":，

"label":"商。

"end":，

"begin":"-1559"

]

返回屬性

屬性類型說明

labelliterial朝代名稱

beginliterial朝代開始時(shí)間

endliterial朝代截止時(shí)間

dynastyliterial朝代

monarchliterial帝王

monarchNameliterial帝王姓名

reignTitleliterial年號(hào)

(6)書目數(shù)據(jù)

功能：輸入題名、責(zé)任者、姓氏、先祖名人姓名、譜籍地名、堂號(hào)、館藏機(jī)構(gòu)、摘

要中的關(guān)鍵詞的任意組合，返回所有匹配的家譜數(shù)據(jù)。數(shù)據(jù)匹配方式為模糊匹配。

升級(jí)內(nèi)容：增加先祖名人的信息返回。記錄條數(shù)最多達(dá)到100條。

API接口：

［參數(shù)lj&key=［參數(shù)2］

輸入：

［參數(shù)1］：詳見*參數(shù)表。（多個(gè)參數(shù)可任意組合，用&鏈接）

［參數(shù)2］:用戶的APIKey

輸出：家譜的JSON-LD數(shù)據(jù)（數(shù)組格式）

*參數(shù)1表

屬性類型說明

titlestring標(biāo)題

creatorstring責(zé)任者

familyNamestring姓氏

placestring譜籍地

titleOfAstring堂號(hào)

orgstring收藏機(jī)構(gòu)

personstring先祖名人姓名

desstring摘要

輸入：

輸出：

(

"@graph":[

(

"@id":

"relatedWork":

),

(

"@id":

"relatedWork":""

),

(

"@id":

"@type":

"category":

"edition":{

},

"extent":“一冊”，

"instanceOf":

"temporalValue":[

”1944年"，

1944

]

},

"@id":""，

"@type":

"heldBy":二

"itemOf":""

"@id":

"@type":

"heldBy":二

"itemOf":""

"@type":

"edition":"不IT,

"identifiedBy":"1160001,；

"subject":

"title":

HH:[

（

"?language":"cht",

"@value":"番禺羽氏族IM二卷（廉柬省廉州市番禺H）N

},

（

"?language":"chs\

"@value":"番禺羽氏族譜二卷（廣東省廣州市番禺區(qū)）"

}

],

"description":"始祖士夫，明代人。一世祖）1麒，字釉漠，明代人」,

"place":""

}

L

"?context":{

"title":{

"@idw:,1

"@type":M@id"

},

"subject":{

"@idn:""，

"@type":"?id"

},

"description":

"place":{

"@type":"@id"

},

"identifiedBy":

"edition":

"relatedWork":{

"@id":

"@type":"@id"

},

"itemOf":{

"@type":"@id"

).

"heldBy":{

"@type":"@id"

},

"extent":二

"instanceOf":{

"@idR::

"@type":w@id"

},

"category":{

"@id":

"@type":"@id"

},

"temporalValue":w"

)

)

返回屬性說明:

屬性類型說明

作品(graph="/jp/resource/work/")

value:正書名

language:語言

titleliterial

"chs":中文簡體

"cht":中文繁體

/vocab/titleURI題名URI

creatorURI責(zé)任者URI

contributorURI其他責(zé)任者URI

姓氏URI("/authority/familyname/")

或

subjectURI

堂號(hào)URI

("/authority/titleofancestraltemple/")

placeURI譜籍地URI

descriptionliterial摘要

實(shí)例(graph="/jp/resource/instance/")

categoryURI分類URI(平裝、線裝、精裝…)

editionURI版本URI(抄本、刻本...)

extentliterial

temporalURI出版年代URI

temporal:Valueliterial出版年代描述

instanceOfURI書目URI

單件(graph="/jp/resource/item/")

*一個(gè)作品可能關(guān)聯(lián)多個(gè)單件

heldByURI館藏機(jī)構(gòu)URI

itemOfURI版本信息URI

shelfMarkliterial索書號(hào)

descriptionliterialD0I

relatedWorkURI家譜URI(此先祖名人屬于哪本家譜)

3.通過SparqlEndpoint獲取數(shù)據(jù)

地址：:8890/sparql

輸入：SPARQL查詢語句

輸出:HTML,RDF/XML,JSON,Turtle等

三，JSON-LD解析

一、JSON(JavaScriptObjectNotation)一種簡單的數(shù)據(jù)格式，比xml更輕巧。

Json建構(gòu)于兩種結(jié)構(gòu)：

1>"名稱/值”對(duì)的集合(Acollectionofname/valuepairs)。不同的語言

中，它被理解為對(duì)象(object),紀(jì)錄(record),結(jié)構(gòu)(struct),字典(dictionary),

哈希表(hashtable),有鍵列表(keyedlist),或者關(guān)聯(lián)數(shù)組(associativearray)。

如：

■

“name"："jackson>,,

“age”：100

2、值的有序列表(Anorderedlistofvalues)?在大部分語言中，它被理解為

數(shù)組(array)如：

{_______

“students”:

[

{"name":"jackson","age”:100},

{"name":"michael","age":51}

]

二、解析JSON步驟(以JAVA為例)

A、服務(wù)器端將數(shù)據(jù)轉(zhuǎn)換成json字符串

首先、服務(wù)器端項(xiàng)目要導(dǎo)入json的jar包和json所依賴的jar包至builtPath

路徑下(這些可以到JSONTib官網(wǎng)下載：)

/&WebRoot

t>0META-INF

,0WEB-INF

，&lib

吧commons-beanutils-1.7.jar

吧commons-collectionsjar

矗commons-lang.jar

山commons-logging-1.1.l.jar

金.ezmorph.jar

山j(luò)son-lib-2.2.2-jdkl5jar

[xfweb.xml

Iindexjsp.

然后將數(shù)據(jù)轉(zhuǎn)為json字符串，核心函數(shù)是：

publicstaticStringcreateJsonString(Stringkey,Objectvalue)

JSONObjectjsonObject二newJSONObject();

jsonObject.put(key,value);

returnjsonObject.toStringO;

)

B、客戶端將json字符串轉(zhuǎn)換為相應(yīng)的javaBean

1、客戶端獲取json字符串

publicclassHttpUtil

publicstaticStringgetJsonContent(StringurlStr)

try

{//獲取HttpURLConnection連接對(duì)象

URLurl=newURL(urlStr);

HttpURLConnectionhttpConn=(H11pURLConnection)url

.openConnection();

//設(shè)置連接屬性

httpConn.setConnectTimeout(3000);

httpConn.setDoInput(true);

httpConn.setRequestMethod(Z，GET/Z);

//獲取相應(yīng)碼

intrespCode=httpConn.getResponseCode();

if(respCode==200)

returnConvertStream2Jsori(httpConn.getInputStream0);

catch(MalformedURLExceptione)

//TODOAuto-generatedcatchblock

e.printStackTrace();

}

catch(lOExceptione)

(

//TODOAuto-generatedcatchblock

e.printStackTrace();

)

〃〃

return;

privatestaticStringConvertStream2Json(InputStream

inputStream)

StringjsonStr=;

//ByteArrayOutputStream相當(dāng)于內(nèi)存輸出流

ByteArrayOutputStreamout=newByteArrayOutputStream();

byte[]buffer=newbyte[1024];

intlen=0;

//將輸入流轉(zhuǎn)移到內(nèi)存輸出流中

try

while((len=inputstream,read(buffer,0,

buffer,length))!=-1)■

■out.…write(buffer,0,len);

//將內(nèi)存流轉(zhuǎn)換為字符串

jsonStr=newString(out.toByteArray());

)

■catch(lOExceptione)

//TODOAuto-generatedcatchblock

■-e.printStackTrace();

returnjsonStr;

2、獲取javaBean