Logo: ZBW Labs

Web Services for Economics (beta)

Version/Change history

As the publisher of the STW Thesaurus for Economics, the ZBW - Leibniz Information Centre for Economics provides experimental economics terminology and authority web services (econ-ws, formerly stw-ws) for use by humans and by machines. The services primarily aim to support resource lookup and query expansion in the context of information retrieval applications.
Parts of the delivered data originate from datasets which were created by third parties and shared through open licenses (see information below).

General Concepts

The services follow the REST design principles.

All services uniformly support the HTTP GET method.

Terminology Services

/suggest - Suggestions for Resources (starting with a given string)

Returns for a query string every matching term (alt or prefered labels, right truncated), the prefered label in the selected language and the URI, ordered by term. (For use in Javascript applications see example.)

Example:
http://zbw.eu/beta/econ-ws/suggest?&query=acc
http://zbw.eu/beta/econ-ws/suggest?dataset=jel&query=e2

Parameters: query, dataset, lang, limit, callback

Result: term, prefLabel, concept

/suggest2 - Suggestions for Resources (optimized for large datasets)

Returns for a query string every matching entry (by label, right truncated) with the preferred name (in larger datasets usually non-unique), a constructed (mostly unique) preferred label in the selected language, and the URI, ordered by descending count of hits in some backend database (as a very vague measure of relevance). (For use in Javascript applications see example.)

Example: http://zbw.eu/beta/econ-ws/suggest2?dataset=econ_pers&query=ke

Parameters: query, dataset (currently only econ_pers and econ_corp), lang, limit, callback

Result: prefName, prefLabel, concept

/synonyms - Alternative Terms for a Search Term (from matching labels)

Returns the alternative search terms, by
1. searching the given term within the preferred and alternate labels of all descriptors,
2. returning all preferred and alternate labels of these descriptors
(not restricted to a certain language).
(Effectively a combination of /concepts and /labels.)

With parameter vocabs=ALL, pref- and altLabels from all matching concepts of other vocabularies (via skos:exactMatch) are included for lookup and returned terms.

Example:
http://zbw.eu/beta/econ-ws/synonyms?query=investment+policy http://zbw.eu/beta/econ-ws/synonyms?query=investment+policy&vocabs=ALL

Parameters: query, vocabs

Result: synonym

/combined1 - Combined Info for Retrieval Applications

Returns for a query string
1. concepts with matching labels (matching is done via a lucene 'or' query against every single label). Results are returned in order of descending scores. Number of results is limited to number of words or less.
2. narrower concepts of the matched concepts
3. related concepts of the matched concepts
4. prefLabels for all concepts
5. alt/hiddenLabels for all concepts
Can be restricted to only one relationship

Example:
http://zbw.eu/beta/econ-ws/combined1?query=free+trade+zone
http://zbw.eu/beta/econ-ws/combined1?query=telework&output=json-ld

Parameters: query, relationship, vocabs (currently stw or ALL implemented), callback, output (RDF output available - experimental)

Result: concept, prefLabel, altLabel, hiddenLabel, narrower, related

/mappings - Mappings for a Concept

Returns all or selected mappings for a concept (or a comma-seperated list of concepts), with its preferred labels.

Example:
http://zbw.eu/beta/econ-ws/mappings?concept=http://zbw.eu/stw/descriptor/19218-6
http://zbw.eu/beta/econ-ws/mappings?concept=http://zbw.eu/stw/descriptor/19218-6&lang=de
http://zbw.eu/beta/econ-ws/mappings?concept=http://d-nb.info/gnd/4291458-9&lang=de&output=html

Parameters: concept, lang, vocabs (NYI, defaults to ALL), output (RDF output available - experimental)

Result: concept, prefLabel, relation, targetPrefLabel, targetConcept, target

Auxiliary Services

These are not strictly terminology services, but maybe useful in the context of STW and other terminologies.

/assigned_descriptors - Retrieves the descriptors assigned to a work

Currently returns a comma-separated list of STW descriptor URIs for a supplied ISBN number, an identifier (currently the according GVK PPN and an informative label (to uncover typos in the isbn), in sparql-json output format. For use in Javascript applications see example. (Highly experimental)

Example:
http://zbw.eu/beta/econ-ws/assigned_descriptors?isbn=978-3-8349-1754-6

Parameters: isbn (10 or 13, required), gvkppn (NYI)

Deprecated Services

The following services had been designed in 2009 in approach to offer programmatic acces to STW. They have seen few practical use, and they can be easily substituted by either the /suggest service (in case of /concepts), or by access to the RDF/RDFa representation of the concept. So they may be dropped in future versions.

/concepts - Search for Thesaurus Concepts

Returns all concepts (by default of subtype zbwext:Descriptor only), where the search term matches prefLabel or altLabel.

Example: http://zbw.eu/beta/econ-ws/concepts?query=audit

Parameters: query, lang

/narrower - Narrower Concepts for a Concept

Returns the narrower concepts of the given concept (by default descriptors only), supplemented with the preferred label in English (default) or German.

Example: http://zbw.eu/beta/econ-ws/narrower?concept=http://zbw.eu/stw/descriptor/12882-1

Parameters: concept, lang

/labels - All Labels for a Concept

Returns prefLabel and altLabels of a given concept.

Example: http://zbw.eu/beta/econ-ws/labels?concept=http://zbw.eu/stw/descriptor/19160-4

Parameters: concept, lang

Common Parameters

dataset
stw (default)
STW Thesaurus for Economics
jel
Journal of Economic Literature (JEL) Classification System by American Economic Association. Translations by André Davids, K.U. Leuven.
econ_pers
A subset of GND (ex-PND, personal names authority file) by German National Library (150,000 economicsts, as referenced in the EconBiz dataset of ZBW, or with economics related professions)
econ_corp
A subset of GND (ex-GKD, corporate names authority file) by German National Library (60,000 economics institutions, as referenced in the EconBiz dataset of ZBW, or institutions which employ economists)
vocabs
Vocabularies to which STW is mapped. These vocabs, and partially the mappings, were contributed by third parties. Currently available are SWD, TheSoz, Agrovoc, DBpedia
stw (default)
restrict to STW
gnd
restrict to GND (SWD)
ALL
All currently mapped vocabularies
lang
en (default)
de
output
Equivalent to "Content-Type" HTTP Request Parameter (NYI). When definded, "output=" takes precedence.
For some services (e.g., /combined1), tree shaped results are a better fit than the classical table-shaped results of a SPARQL SELECT query. Therefore, we add experimental support for RDF output formats (based on SPARQL CONSTRUCT) for certain services (see service documentation).
html
returns SPARQL results as a human readable HTML page (by xml + xslt stylesheet)
Content-Type: application/xml; charset=UTF-8
sparql-xml
returns SPARQL results in XML, according to the W3C Recommendation SPARQL Query Results XML Format
Content-Type: application/sparql-results+xml
sparql-json (default)
returns SPARQL results in JSON, according to the W3C Note Serializing SPARQL Query Results in JSON
Content-Type: application/sparql-results+json; charset=utf-8
text (experimental)
returns SPARQL results formatted as a textual table
Content-Type: text/plain; charset=UTF-8
json-ld (experimental)
returns a RDF graph in JSON-LD. Available only when mentioned in service description.
Content-Type: application/ld+json; charset=UTF-8
turtle (experimental)
returns a RDF graph in Turtle. Available only when mentioned in service description.
Content-Type: text/turtle
n-triples (experimental)
returns a RDF graph in N-Triples. Available only when mentioned in service description.
Content-Type: text/plain
rdf-xml (experimental)
returns a RDF graph in RDF/XML. Available only when mentioned in service description.
Content-Type: application/rdf+xml
concept
URI of the Concept
query
Search String, URI-escaped if necessary. If not mentioned otherwise, exact (though case-insensitive) matches are performed.
relationship
broader / narrower / related / NONE
Include descriptors with skos:broader, skos:narrower, skos:related relationship to matching descriptors. (default is a combination of narrower and related. Use NONE to get no releationships at all.)
limit
maximal number of results (default: 10)
callback
Name of a (Javascript) callback routine to wrap the result (only for JSON output format).

Error Handling

In case of a server side error, HTTP response codes 5xx are returned. In case of a client side error, HTTP response code 400 ("Bad Request") and a short message are returned.

Implementation

The beta version is implemented using Fuseki SPARQL server (from the Apache Jena toolkit) and a PHP wrapper. It makes use of the Jena Text component included in recent versions of Fuseki. For json-ld output, the JsonLD library is used.

A public SPARQL Endpoint (http://zbw.eu/beta/sparql) is available.

Comments, queries and suggestions are greatly appreciated.

Changes

0.65 (2013-11-11)
Use STW 8.12 and updated mappings, with fixed GND/SWD skos:altLabels (see v0.54 below).
Fixed case-sensitivity in /suggest2 service.
0.64 (2013-09-18)
Add support for RDF output formats for /mappings.
Add /mappings and /combined1 examples (with visualization of resulting RDF graphs).
Fix bug in /suggest (hyphenated terms not found).
0.63 (2013-08-01)
Add json-ld output format (currently limited to /combined1).
0.62 (2013-07-26)
Add experimental support for output in RDF formats (currently limited to /combined1).
Add option relationship=NONE
Fix a bug in suggest (trailing space causes Data server error)
0.60 (2013-07-03)
Web service code refactored to clean up and to take advantage of Fuseki.
The output parameter is now generally available in terminology services.
Default output format has switched from "html" to "sparql-json".
The defunct "match" and "score" return values of /combined1 has been dropped.
The limit parameter has been implemented.
0.55 (2013-07-01)
SPARQL backend switched to Fuseki (from former use of Joseki and sparqlite)
0.54 (2012-08-27)
skos:altLabels from GND/SWD removed from dataset stw_mapping because of severe problems in /synonyms service caused by this
0.53 (2012-07-24)
Dataset econ_corp added
0.52 (2012-06-12)
jel dataset now in en/de/fr/es languages
econ_person dataset now based on GND as of 2012-04
0.51 (2012-05-21)
Fixed Bug in /assigned_descriptors and indexing example caused by upstream changes
0.50 (2012-03-30)
"STW Web Services" renamed to "Web Services for Economics"
new URI http://zbw.eu/beta/econ-ws
(http://zbw.eu/beta/stw-ws is deprecated now, but will still be supported)
dataset "econ_pnd" renamed to "econ_pers"
/concepts, /narrower and /labels services are deprecated now
0.41 (2012-03-26)
CORS support added
0.40 (2012-02-01)
fixed: accidentally changed binding in /synonyms service, now ?synonym again
0.39 (2011-12-08)
Econis link added to suggest2 example
fixed: missing target in /mappings service
0.38 (2011-11-21)
new service /assigned_descriptors (with example STW to SWD (GND) mapping application)
/combined1 service extended by mappings to other vocabs
0.37 (2011-11-15)
/synonyms service extended by mappings to other vocabs
/suggest2 example with links to EconBiz portal
0.36 (2011-11-10)
based on STW v8.08 with mappings to SWD, TheSoz, Agrovoc, DBpedia
new service /mappings
new service /suggest2 for econ_pnd
thesoz dataset not included any more
0.35 (2011-04-15)
dataset econ_pnd added
dataset thesoz upgraded to v 0.7
experimental dataset pnd removed
experimental dataset lcsh removed
0.34 (2010-09-14)
skos:altLabel for dataset jel added
0.33
subset of PND for 20th Century Press Archives added
0.32
very experimental access to LCSH added
0.31
Example for use of /suggest in Javascript added
0.30 (2010-03-06)
added relationship parameter (for /combined1)
0.29
/suggest extended to TheSoz vocabulary
0.28 (2009-09-06)
added dataset parameter; /suggest extended to JEL vocabulary; new output parameter (format deprecated now)
0.27 (2009-09-01)
experimental /combined1 service added; link to SPARQL Endpoint
0.26
experimental callback parameter
0.25 (2009-04-29)
links to zbwext vocab; typos
0.24 (2009-04-22)
basic /suggest service added
0.23 (2009-03-30)
first public version

ZBW, 2013-11-11 13:23:16   (Imprint)

Valid XHTML + RDFa