DARIAH-DE Normdatendienste

Thesaurus of Geographical Names (Getty)

RESTful API

This DARIAH-DE's Getty service currently is using life data from getty.edu.

The API for DARIAH-DE's Getty service provides several possible usages:

• by providing the beginning of a place name
• by providing the exact place name
• a place's Getty Thesaurus ID

Queries are case insensitive. The autocomplete and exact match modes return a custom XML by default, but a JSON output can be retrieved by appending .json to the REST path (confer examples for usage).

Autocomplete

• /tgn/v1/starts-with(.json)?q=beginning-of-some-place-name

  • returns the place name where the place is located, and the Getty ID
  • XML example: https://ref.de.dariah.eu/tgn/v1/starts-with?q=vagen
  • JSON example: https://ref.de.dariah.eu/tgn/v1/starts-with.json?q=vagen

• /tgn/v1/starts-with(.json)?q=beginning-of-some-place-name&georef=true-or-false

  • returns the place name where the place is located, the Getty ID, and the Geo coordinates (longitude and latitude)
  • XML Example: https://ref.de.dariah.eu/tgn/v1/starts-with?q=vagen&georef=true
  • JSON example: https://ref.de.dariah.eu/tgn/v1/starts-with.json?q=vagen&georef=true

• /tgn/v1/starts-with(.json)?q=beginning-of-some-place-name&details=true-or-false

  • Returns the place namewhere the place is located, the Getty ID, the Geo coordinates (longitude and latitude), and the link to RDF data set of the place in TNG
  • XML example: https://ref.de.dariah.eu/tgn/v1/starts-with?q=vagen&details=true
  • JSOn example https://ref.de.dariah.eu/tgn/v1/starts-with.json?q=vagen&details=true

Exact matches

• /tgn/v1/exact-match(.json)?q=exact-place-name

  • Returns the Place name where the place is located, and the Getty ID
  • XML example: https://ref.de.dariah.eu/tgn/v1/exact-match?q=scharzfeld
  • JSOn example: https://ref.de.dariah.eu/tgn/v1/exact-match.json?q=scharzfeld

• /tgn/v1/exact-match(.json)?q=exact-place-name&georef=true-or-false

  • Returns the Place name where the place is located, the Getty ID, and the Geo coordinates (longitude and latitude)
  • XML example: https://ref.de.dariah.eu/tgn/v1/exact-match?q=scharzfeld&georef=true
  • JSOn example: https://ref.de.dariah.eu/tgn/v1/exact-match.json?q=scharzfeld&georef=true

• /tgn/v1/exact-match(.json)?q=exact-place-name&details=true-or-false

  • Returns the Place name where the place is located, the Getty ID, the Geo coordinates (longitude and latitude), and the link to RDF data set of the place in TNG
  • XML example: https://ref.de.dariah.eu/tgn/v1/exact-match?q=scharzfeld&details=true
  • JSON exasmple: https://ref.de.dariah.eu/tgn/v1/exact-match.json?q=scharzfeld&details=true

Result by Getty ID

• /tgn/v1/getty-id(.rdf)

  • Returns the full RDF data set at http://vocab.getty.edu/tgn/getty-id.rdf
  • Example: https://ref.de.dariah.eu/tgn/v1/7003670.rdf

• /tgn/v1/getty-id.json

  • Returns the full JSON data set of http://vocab.getty.edu/tgn/getty-id
  • Example: https://ref.de.dariah.eu/tgn/v1/7003670.json

• /tgn/v1/getty-id.jsonld

  • Returns the full JSONLD data set of http://vocab.getty.edu/tgn/getty-id
  • Example: https://ref.de.dariah.eu//tgn/v1/7003670.jsonld

• /tgn/v1/getty-id.n3

  • Returns the full N3/Turtle data set of http://vocab.getty.edu/tgn/getty-id
  • Example: https://ref.de.dariah.eu/tgn/v1/7003670.n3

• /tgn/v1/getty-id.nt

  • Returns the full N-Triples data set of http://vocab.getty.edu/tgn/getty-id
  • Example https://ref.de.dariah.eu/tgn/v1/7003670.nt

RESTful API (deprecated)

DARIAH-DE's Getty service currently runs on a (n relatively old) TGN dump in an eXist-db.

• ?ac=xxx – autocompletion, returns every hit starting with xxx: https://ref.de.dariah.eu/tgnsearch/tgnquery.xql?ac=Bam
• ?ln=xxx – long, returns more detailed information on place xxx: https://ref.de.dariah.eu/tgnsearch/tgnquery.xql?ln=berlin
• ?id=xxx – identifier, returns everything about place with id xxx: https://ref.de.dariah.eu/tgnsearch/tgnquery.xql?id=7004325

Gemeinsame Normdatei (GND)

Live requests from current DNB GND via SRU, persons only

RESTful API

• ?ac=xxx – autocompletion, returns every hit starting with xxx: https://ref.de.dariah.eu/pndsearch/pndquery.xql?ac=Ringel
• ?ln=xxx – long, returns more detailed information on person xxx: https://ref.de.dariah.eu/pndsearch/pndquery.xql?ln=Ringeln
• ?id=xxx – identifier, returns everything about person with id xxx: https://ref.de.dariah.eu/pndsearch/pndquery.xql?id=118601121

It is possible to retrieve the whole dataset in RDF from https://d-nb.info/gnd/118601121/about.

Advanced Usage (Passing SRU Parameters)

You also can use DNB parameters, as stated in https://services.dnb.de/sru/dnb?operation=explain&version=1.1, for they are piped through, such as "dnb.sw" or "dnb.geo".

• Search for names: https://ref.de.dariah.eu/pndsearch/pndquery.xql?ln=W%C3%B6hler
• Search for professions: https://ref.de.dariah.eu/pndsearch/pndquery.xql?ln=W%C3%B6hler%20and%20dnb.sw=Soziologe
• Search for refined names: https://ref.de.dariah.eu/pndsearch/pndquery.xql?ln=W%C3%B6hler%20and%20dnb.sw=Soziologe%20and%20dnb.geo=Heidelberg

You can also get RDF or JSON responses using requests such as https://ref.de.dariah.eu/pndsearch/rdf?ln=W%C3%B6hler or https://ref.de.dariah.eu/pndsearch/json?ln=W%C3%B6hler

OpenAPI Documentation and SwaggerUI

is also available, please see https://ref.de.dariah.eu/doc/api/index.html