.. _unlock:
##########################
The Edina *Unlock* Service
##########################
Apart from `Geonames `_, the online
gazetteers referenced by the geoparser are all hosted by `Edina
`_'s `Unlock service
`_. There are two web services, *Unlock
Places* and *Unlock Text*.
Unlock Places
=============
`Unlock Places `_ provides an API
to allow the user to match a placename string against one or more
gazetteers. The geoparser uses this to find candidate locations for
placename strings extracted by the geotagging step. The API provides a
simple and flexible way to search different gazetteers, with results
available in a range of formats.
For example:
`http://unlock.edina.ac.uk/ws/search?name=Edinburgh `_
returns an xml file of candidate locations matching "Edinburgh" (108
candidates at time of writing) from all the available gazetteers,
including whatever attributes the gazetteer provides - such as
latitude, longitude, feature codes, population and alternative names.
To restrict the search to a particular gazetteer one simply specifies
it in the request:
`http://unlock.edina.ac.uk/ws/search?name=Halicarnassus&gazetteer=plplus `_
This returns matches for "Halicarnassus" in the copy of Pleiades+
hosted by Edina. (See :ref:`Pleiades+ ` discussion in the
Gazetteers chapter for more on versions of Pleiades.)
See the `Unlock Places `_ website
for documentation and examples of use of the service.
Unlock Text
===========
The `Unlock Text `_ API is a more
sophisticated tool and requires the user to create an account. It
allows you to submit complete texts for geoparsing, either
individually or in bundles. It is, in effect, an online version of the
geoparser pipeline and is probably the simplest way of using the
geoparser, if no customisation is required. There are subtle and
unavoidable differences between the Unlock version and the
downloadable geoparser package, meaning that results will not
necessarily be identical. If your needs are complex it may be better
to install a local copy of the geoparser.
See `Getting Started with Unlock Text
`_ for how to use the
online service. At the time of writing, a visualisation component is
in development, so that users can submit full texts and see map-based
results immediately.
At the time of writing the Unlock Text documentation doesn't
explicitly show how to use the Pleiades+ gazetteer hosted by Edina,
but this can be specified much as for the Unlock Text example above,
by including a ``gazetteer:gazname`` pair in the JSON data item for
"src", like this::
{"src":"http://synapse.inf.ed.ac.uk/~kate/gap/unlockTests/book9plain.txt",
"gazetteer":"plplus"}
For more on using Unlock Text with classical works, see blog posts on
the Google Ancient Places (GAP) project at `Unlocking Text
`_
and `Even More Unlocked
`_. The
*GapVis* interface (`version 1
`_ and `version 2
`_) uses Unlock Text as part
of its back-end engine, to produce an interface to Herodotus'
*Histories* and other texts, for students of classics.