Web Services for Economics (beta)
Version/Change history
As the publisher of theSTW Thesaurus for Economics, theZBW - Leibniz Information Centre forEconomics providesexperimental economicsterminology and authority web services (econ-ws, formerly stw-ws) for use byhumans and by machines. The services primarily aim to support resource lookupand query expansion in the context of information retrieval applications.
Parts of the delivered data originate from datasets which were created by thirdparties and shared through open licenses (seeinformation below).
General Concepts
The services follow theREST 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 applicationsseeexample.)
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
/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+policyhttp://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 onerelationship
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 ofconcepts), 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 STWconcept over multiple versions (making use ofskos-history).
Parameters:concept,output (RDF only)
Deprecated Services
The following services had been designed in 2009 in approach to offerprogrammatic acces to STW. They have seen few practical use, and they canbe 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 bedropped 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 byAmerican Economic Association.Translations by André Davids, K.U. Leuven.
- vocabs
- Vocabularies to which STW is mapped. These vocabs, and partially themappings, were contributed by third parties. Currently available areSWD,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 fitthan the classical table-shaped results of a SPARQL SELECT query. Therefore, weadd 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 + xsltstylesheet)
- Content-Type: application/xml; charset=UTF-8
- sparql-xml
- returns SPARQL results in XML, according to the W3C RecommendationSPARQL Query Results XMLFormat
- Content-Type: application/sparql-results+xml
- sparql-json (default)
- returns SPARQL results in JSON, according to the W3C NoteSerializing SPARQL QueryResults 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 inJSON-LD. Available only when mentioned in service description.
- Content-Type: application/ld+json; charset=UTF-8
- turtle(experimental)
- returns a RDF graph inTurtle.Available only when mentioned in service description.
- Content-Type: text/turtle
- n-triples(experimental)
- returns a RDF graph inN-Triples.Available only when mentioned in service description.
- Content-Type: text/plain
- rdf-xml(experimental)
- returns a RDF graph inRDF/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:relatedrelationship to matching descriptors. (default is a combination of narrowerand 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. Incase of a client side error, HTTP response code 400 ("Bad Request") and a shortmessage are returned.
Implementation
The beta version is implemented usingFusekiSPARQL server (from the Apache Jena toolkit) and a PHP wrapper. It makesuse of the Jena Text component included in recent versions of Fuseki. For json-ld output, theJsonLDlibrary is used.
A publicSPARQL Endpoint (http://zbw.eu/beta/sparql) is available.
Comments, queries and suggestions are greatly appreciated.
Changes
- 0.75 (2024-01-25)
- Remove experimental datasets econ_pers and econ_corp and the service/suggest2 (which was developed specifically for these datasets)
- Remove examples section (which used obsolete Javascript libaries)
- 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 (withvisualization 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.
- Theoutput parameter is now generally availablein terminology services.
- Default output format has switched from "html" to "sparql-json".
- The defunct "match" and "score" return values of/combined1has been dropped.
- Thelimit parameter has been implemented.
- 0.55 (2013-07-01)
- SPARQL backend switched toFuseki(from former use ofJoseki andsparqlite)
- 0.54 (2012-08-27)
- skos:altLabels from GND/SWD removed from dataset stw_mapping because of severe problems in /synonyms service caused bythis
- 0.53 (2012-07-24)
- Datasetecon_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 URIhttp://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 tosuggest2 example
- fixed: missing target in /mappings service
- 0.38 (2011-11-21)
- new service/assigned_descriptors (withexample 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 toSWD,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 for20th 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)
- addedrelationship parameter (for /combined1)
- 0.29
- /suggest extended to TheSoz vocabulary
- 0.28 (2009-09-06)
- addeddataset parameter; /suggest extended to JEL vocabulary; newoutput 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