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
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=https://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
/concept-history - History of a SKOS Concept
Returns an RDF file about triple insertions and deletions in regard to a STW concept over multiple versions (making use of skos-history).
Parameters: concept, output (RDF only)
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
/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
/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
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.74 (2023-03-01)
- Include altLabelNarrower and altLabelRelated in /suggest
- 0.73 (2022-12-05)
- Fix searches including apostroph (and similar)
- 0.72 (2018-08-20)
- Remove highly experimental /assigned_descriptors service
- Remove examples files using defunct 3rd party graph service (mapping_graph, combined1_graph)
- 0.71 (2016-11-03)
- Suggest only current corporate bodys (which have no successor).
- Fix bug for multi-word queries in /suggest2.
- 0.70 (2016-05-03)
- For RDF outputs, mark concepts found by searching in /combined1 with zbwext:Found. (Experimental)
- Set jsonld option compactArrays to false.
- 0.69 (2016-04-22)
- Deployment changes and refactoring (to avoid client-visible redirect).
- 0.68 (2015-07-30)
- Use latest GND version (2015-05-13) for econ_pers and econ_corp.
- 0.67 (2015-06-30)
- Use STW 9.0 and updated mappings.
- Add experimental /concept-history service.
- 0.66 (2015-01-06)
- Use STW 8.14.
- 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