OnDemand Users - Please read this important announcement!

GeoTagger API

The GeoTagger offers output in 4 formats:

• JSON -- The most fully featured format, the JSON format includes all the available information about the locations.
• KML -- A more lightweight format, but suitable for use in applications which use KML.
• GeoMarkup -- an XML format which contains more information about possible places returned, allowing you to see what alternative options exist for a specific geographic reference, but limited information for creating a map.
• PNG -- An image output format, which will return an image with the locations returned displayed on the image.

The purpose of the GeoTagger API is to take a document, either by passing a URL via the 'url' parameter, or passing a string via the 'doc' parameter, and return the geographic references contained in that document.

The GeoTagger offers a number of different 'actions' for the JSON output. These actions allow you to choose what level of information is available in your output.

• getDocumentReferences -- the simplest, and fastest, form, this method returns a set of References in the document, each with a location and their associated confidences. Little other information is returned. This output format is preferred if you simply want to get a list of the points described in a given document.
• getLocationReferences -- This form reorganizes the references to be organized by locations. This means that if the same location is mentioned multiple times in a document, it will be de-duplicated, and you will get a list of references for each location.
• getEnhancedLocationReferences -- This form adds additional information about the location, such as the "Path" for the location, and the ViewBox for the location, which is designed to be a reasonable sized area that a map should show if the location is being displayed on a map. This is likely the most useful method for displaying geotagged locations on a map.

To form a request URL:

• Start with http://ondemand.metacarta.com/webservices/GeoTagger/
• Append the format, one of GeoMarkup, JSON, KML, or PNG: http://ondemand.metacarta.com/webservices/GeoTagger/JSON
• Choose an authentication method: one of session or basic: http://ondemand.metacarta.com/webservices/GeoTagger/JSON/basic
• Append the appropriate parameters to the request, as described below.

Examples of Usage

• OpenLayers Client: GeoTagger Example

Request Parameters

version:

Required
default value: input other than the allowed value raises an error message
allowed values: 1.0.0
usage: The requestor must specify the API version they wish to use. The API requires a valid version parameter.

doc:

Required
default value: ''
allowed values: string
usage: The 'doc' parameter allows you to send a body of text you wish to be parsed by the GeoTagger. One of doc or url is required.

url:

Required
default value: ''
allowed values: string
usage: The 'url' parameter allows you to send a URL you wish to be parsed. It will be requested from a server, using the User-Agent provided as a parameter, and then parsed in the same way as a 'doc' request.

action:

Optional
default value: 'getLocationReferences'
allowed values: 'getLocationReferences', 'getDocumentReferences', 'getEnhancedLocationReferences', 'getEnhancedLocationExtracts'
usage: The 'action' parameter determines the type of data returned by the JSON output format.

useragent:

Optional
default value: Mozilla/5.0 (MetaCarta GeoTagger Web Service; support@metacarta.com)
allowed values: string
usage: The User-Agent used when requesting a page from a remote webserver.

mime:

Optional
default value: text/plain
allowed values: string
usage: The mime type of the content. "text/html" will turn on DOM traversal when possible, returning XPath for references.

mingeoconfidence:

Optional
default value: 0.0
allowed values: float
usage: Defines the minimum confidence for returned results. If results do not exceed this confidence, they are not returned.

bbox:

Optional
default value: -180,-90,180,90
allowed values: a comma separated string of minlon,minlat,maxlon,maxlat
usage: Defines the query's geographic extent. Results outside this extent are dropped from the response.

width:

Optional
default value: 512
allowed values: positive integer
usage: Determines the width of the image returned by the PNG GeoTagger output.

height:

Optional
default value: 383
allowed values: positive integer
usage: Determines the height of the image returned by the PNG GeoTagger output.