Web Services for Economics (beta)

Version 0.54

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. Result is currently limited to 10 entries and sparql-json output format. (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 (NYI), callback

Result: term, prefLabel, concept, notation (for classifications)

/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). Result is currently limited to 10 entries and sparql-json output format. (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), lang, limit (NYI), 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
Result is currently limited to sparql-json output format. ?score doesn't work yet.

Example: http://zbw.eu/beta/econ-ws/combined1?query=free+trade+zone

Parameters: query, relationship, vocabs (currently stw or ALL implemented), callback

Result: match, score, 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

Parameters: concept, lang, vocabs (NYI, defaults to ALL)

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, concept_type (NYI)

/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, concept_type (NYI)

/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_pnd

deprecated - use econ_pers (PND and GKD are merged to GND, so the old name doesn't make sense any more)

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.

html (default)

returns 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: Content-Type: application/sparql-results+xml

sparql-json

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

format

deprecated - please use output

concept

URI of the Concept

query

Search String, URI-escaped if necessary. Presently, exact (though case-insensitive) matches are performed.

concept_type

descriptor (default)

Only concepts from the descriptors part of the STW (zbwext:Descriptor)

thsys

Only concepts from the systematic part of the STW (zbwext:Thsys)

all

All STW sub-types of skos:Concept

relationship

broader / narrower / related

Include descriptors with skos:broader, skos:narrower, skos:related relationships to matching descriptors

limit

maximal number of results

callback (experimental)

Name of a (Javascript) callback routine to wrap the result (only for JSON output format).
Currently works only with "/suggest" and "/combined1".

Error Handling

Error handling is still quite rudimental. 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 Joseki SPARQL server (from the Jena toolkit) and a simple PHP wrapper. A SPARQL Endpoint (http://zbw.eu/beta/sparql) is available also. It is powerd by sparqlite and based on Jena and LARQ. This one is used for the /combined1 service.

Comments, queries and suggestions are greatly appreciated.

Changes

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

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

added relationship parameter (for /combined1)

0.29

/suggest extended to TheSoz vocabulary

0.28

added dataset parameter; /suggest extended to JEL vocabulary; new output parameter (format deprecated now)

0.27

experimental /combined1 service added; link to SPARQL Endpoint

0.26

experimental callback parameter

0.25

links to zbwext vocab; typos

0.24

basic /suggest service added

0.23

first public version