RESTful API¶
The following Nordlys services can be accessed through a RESTful API:
Below we describe the usage for each of the services.
The Nordlys endpoint URL is http://api.nordlys.cc/ .
Entity Retrieval¶
The service presents a ranked list of entities in response to an entity-bearing query.
Endpoint URI¶
http://api.nordlys.cc/er
Example¶
Request:
Response:
{"query": "total recall",}
"total_hits": 1000",
"results": {
"0": {
"entity": "<dbpedia:Total_Recall_(1990_film)>",
"score": -10.042525028471253
},
"1": {
"entity": "<dbpedia:Total_Recall_(2012_film)>",
"score": -10.295316626850521
},
...
}
Parameters¶
The following table lists the parameters needed in the request URL for entity retrieval.
Parameters | |
---|---|
q (required) | Search query |
1st_num_docs | The number of documents that will be re-ranked using a model. The recommended value (esp. for baseline comparisons) is 1000. Lower values, like 100, are recommended only when efficiency matters (default: 1000). |
start | Starting offset for ranked documents (default:0). |
fields_return | Comma-separated list of fields to return for each hit (default: “”). |
model | Name of the retrieval model; Accepted values: “bm25”, “lm”, “mlmprms” (default: “lm”).
|
field | The name of the field used for LM (default: “catchall”). |
fields | Comma-separated list of the fields for PRMS (default: “catchall”). |
field_weights | Comma-separated list of fields and their corresponding weights for MLM (default: “catchall:1”). |
smoothing_method | Smoothing method for LM-based models; Accepted values: jm, dirichlet (default: “dirichlet”). |
smoothing_param | The value of smoothing parameters (lambda or mu); Accepted values: float, “avg_len” (default for “jm”: 0.1, default for “dirichlet”: 2000). |
Entity Linking in Queries¶
The service identifies entities in queries and links them to the corresponding entry in the Knowledge base (DBpedia).
Endpoint URI¶
http://api.nordlys.cc/el
Example¶
Response:
{ "processed_query": "total recall", "query": "total recall", "results": [ { "entity": "<dbpedia:Total_Recall_(1990_film)>", "mention": "total recall", "score": 0.4013333333333334 }, { "entity": "<dbpedia:Total_Recall_(2012_film)>", "mention": "total recall", "score": 0.315 } ] }
Parameters¶
The following table lists the parameters needed in the request URL for entity linking.
Parameters | |
---|---|
q (required) | The search query |
method | The name of method; Accepted values (default: “cmns”)
|
threshold | The entity linking threshold (default: 0.1). |
Target Type Identification¶
The service assigns target types (or categories) to queries from the DBpedia type taxonomy.
Endpoint URI¶
http://api.nordlys.cc/tti
Example¶
- Request:
Response:
{ "query": "obama", "results": { "0": { "score": 3.3290777, "type": "<dbo:Ambassador>" }, "1": { "score": 3.2955842, "type": "<dbo:Election>" }, ... }
Parameters¶
The following table lists the parameters needed in the request URL for target type identification.
Parameters | |
---|---|
q (required) | The search query |
method | The name of method; accepted values: “tc”, “ec”, “ltr” (default: “tc”).
|
num_docs | The number of top ranked target types to retrieve (default: 10). |
start | The starting offset for ranked types. |
model | Retrieval model, if method is “tc” or “ec”; Accepted values: “lm”, “bm25”. |
ec_cutoff | If method is “ec”, rank cut-off of top-K entities for EC TTI. |
field | Field name, if method is “tc” or “ec”. |
smoothing_method | If model is “lm”, smoothing method; accepted values: “jm”, “dirichlet”. |
Smoothing_param | If model is “lm”, smoothing parameter; accepted values: float, “avg_len”. |
Entity Catalog¶
This service is used for representing entities (with IDs, name variants, attributes, and relationships). Additionally, it provides statistics that can be utilized, among others, for result presentation (e.g., identifying prominent properties when generating entity cards).
Endpoint URI¶
http://api.nordlys.cc/ec
Look up entity by ID¶
Request:
http://api.nordlys.cc/ec/lookup_id/<entity_id>
Example:
http://api.nordlys.cc/ec/lookup_id/<dbpedia:Albert_Einstein>
Response:
{ "<dbo:abstract>": ["Albert Einstein was a German-born theoretical physicist ... ], "<dbo:academicAdvisor>": ["<dbpedia:Heinrich_Friedrich_Weber>"], "<dbo:almaMater>": [ "<dbpedia:ETH_Zurich>", "<dbpedia:University_of_Zurich>" ], "<dbo:award>": [ "<dbpedia:Nobel_Prize_in_Physics>", "<dbpedia:Max_Planck_Medal>", ... ], "<dbo:birthDate>": ["1879-03-14"], ... }
Look up entity by name (DBpedia)¶
Looks up an entity by its surface form in DBpedia.
Request:
http://api.nordlys.cc/ec/lookup_sf/dbpedia/<sf>
Example:
Response:
{ "_id": "new york" "<rdfs:label>" : { "<dbpedia:New_York>": 1 } "<dbo:wikiPageDisambiguates>": { "<dbpedia:Manhattan>": 1, "<dbpedia:New_York,_Kentucky>": 1, ... } ... }
Look up entity by name (FACC)¶
Looks up an entity by its surface form in FACC.
Request:
http://api.nordlys.cc/ec/lookup_sf/facc/<sf>
Example:
Response:
{ "_id" : "new york", "facc12" : { "<fb:m.02_286>": 18706787, "<fb:m.02_53fb>": 49, "<fb:m.02_b9l>": 87, "<fb:m.02_l43>": 12, "<fb:m.02_l5n>": 23963, ... } }
Map Freebase entity ID to DBpedia ID¶
Request:
http://api.nordlys.cc/ec/freebase2dbpedia/<fb_id>
Example:
http://api.nordlys.cc/ec/freebase2dbpedia/<fb:m.02_286>
Response:
{ "dbpedia_ids": [ "<dbpedia:New_York_City>" ] }
Map DBpedia entity ID to Freebase ID¶
Request:
http://api.nordlys.cc/ec/dbpedia2freebase/<dbp_id>
Example:
http://api.nordlys.cc/ec/dbpedia2freebase/<dbpedia:New_York>
Response:
{ "freebase_ids": [ "<fb:m.059rby>" ] }
Parameters¶
The following table lists the parameters needed in the request URL for entity catalog.
Parameter | |
---|---|
entity id | It is in the form of “<dbpedia:XXX>”, where XXX denotes the DBpedia/Wikipedia ID of an entity. |
sf | Entity surface form (e.g., “john smith”, “new york”). It needs to be url-escaped. |
fb_id | Freebase ID |
bdp_id | DBpedia ID |
References¶
[1] Jay M Ponte and W Bruce Croft . 1998. A Language modeling approach to information retrieval. In Proc. of SIGIR ‘98. 275–281.
[2] Paul Ogilvie and Jamie Callan. 2003. Combining document representations for known-item search. Proc. of SIGIR ‘03 (2003), 143–150.
[3] Jinyoung Kim, Xiaobing Xue, and W Bruce Croft . 2009. A probabilistic retrieval model for semistructured data. In Proc. of ECIR ‘09. 228–239.
[4] Faegheh Hasibi, Krisztian Balog, and Svein Erik Bratsberg. 2016. Exploiting entity linking in queries for entity retrieval. In Proc. of ICTIR ’16. 171–180. [BIB] [PDF]
[5] Faegheh Hasibi, Krisztian Balog, and Svein Erik Bratsberg. 2015. Entity linking in queries: Tasks and Evaluation. In Proc. of ICTIR ’15. 171–180. [BIB] [PDF]
[6] Krisztian Balog, Robert Neumayer. 2012. Hierarchical target type identification for entity-oriented queries. In Proc. of CIKM ‘12. 2391–2394. [BIB] [PDF]
[7] Shuo Zhang and Krisztian Balog. Design Patterns for Fusion-Based Object Retrieval. In Proc. of ECIR ‘17. 684-690. [BIB] [PDF]
[8] Darío Garigliotti, Faegheh Hasibi, and Krisztian Balog. Target Type Identification for Entity-Bearing Queries. In Proc. of SIGIR ‘17. [BIB] [PDF]
[9] Faegheh Hasibi, Krisztian Balog, and Svein Erik Bratsberg. 2017. Entity linking in queries: Efficiency vs. Effectiveness. In Proc. of ECIR ’17. 40-53. [BIB] [PDF]