Open Context RESTful Web-Services Documentation
Open Context provides a simple web services to get content expressed in XHTML (for human use in browsers), the supported Atom Syndication Format (plus GeoRSS extensions), JSON (Javascript Object Notation), and KML (the format used by GoogleEarth). The Atom-based web services provide a powerful set of query options to request items from a collection. Query parameters include: geographic, chronological, descriptive (based on how items are described), and social (based on relations between people and organizations and items from a collection). All the results of queries are expressed as Atom feeds, an open format representing one of the most widely deployed and supported standards on the Web. By expressing query results in Atom (and JSON or KML), Open Context collections can be easily recombined with collections from Flickr in innovative mashups, or with news items from journalists or bloggers, or even displayed in personal profile in Facebook.
You can make queries to Open Context with queries specified in a number of dimensions as indicated in Table 1 below. Note, a very similar web-service is available for images. Simply replace 'sets' with 'lightbox' to get image items.
In addition to the services described below, Open Context is registered in the OAI database of conforming repositories. Open Context's OAI-PMH (Ver. 2) service is located at: http://opencontext.org/oai/request (Note: Add OAI-PMH parameters)
Table 1: Query Parameters to Retrieve Sets of Items
|
Parameter |
Possible Values |
Description |
|---|---|---|
|
(Context path) |
Slash separated values of URL-encoded text |
This represents spatial containment “paths” with larger locations and objects containing nested (child) locations and objects. Example: http://opencontext.org/sets/Turkey/Domuztepe/I/Lot+1704 retrieves items from inside Lot 1704 at Domuztepe, Operation I. |
|
q |
URL-encoded text |
This works like Google's search, and performs a full-text search of Open Context. Multiple text values can be passed to this, or you can search for an exact phrase by placing the phrase in quotes. Example: http://opencontext.org/sets/?q=gold retrieves items with "gold" somewhere in their description. |
|
bBox |
Comma separated list of 4 numbers representing decimal degree coordinates (WGS84 datum). |
These four arguments are used together to form a quadrant of the earth's surface for locating data. The first two numbers represent the coordinates of the south-west corner of the bounding box, while the last two numbers represent the coordinates of the north-east corner of the bounding box. Example: http://opencontext.org/sets/?bBox=30,30,50,50 retrieves items located in the region bound by the coordinates: 30E, 30N to 50E, 50N (very roughly southwest Asia). |
|
proj |
URL-encoded text |
This parameter filters by the names of projects / collections. Limit of 128 characters. Example: http://opencontext.org/sets/?proj=Domuztepe+Excavations retrieves items from the "Domuztepe Excavations" project. |
|
cat |
URL-encoded text |
This parameter filters content by its general category (“animal bone”, “small finds”, etc.) Example: http://opencontext.org/sets/?cat=Small+Find retrieves items described by the general category "Small Finds". |
|
prop[*] |
URL-encoded text (variable names within the square brackets)
URL-encoded text (values for the parameter represent values for the variable indicated in the square brackets. Numeric values can be proceeded by 'URL-encoded '>', '>=', '<', or '<=' to make range queries.) |
This parameter is for querying descriptive properties. Properties are variable / value pairs in Open Context, and they represent the how data providers describe their observations. The name of the variable is indicated in the square bracket, and the corresponding value for the property is indicated by the value assigned to this parameter. Example A: http://opencontext.org/sets/?cat=Small+Find&prop%5BObject%5D=Lamp retrieves items described by the general category "Small Finds", and described by the property "Object" (variable), "Lamp" (value). Example B: http://opencontext.org/sets/?proj=Domuztepe+Excavations&prop%5BFragment+Length+%28mm%29%5D=%3E%3D116,%3C174 retrieves items from the "Domuztepe Excavations" project, described by the property "Fragment Length (mm)" (variable), with values ranging from 116 to 174. |
|
person |
URL-encoded text |
This parameter filters content by individual people and organizations associated with the content (authors, observers, analysts, etc.). Example: http://opencontext.org/sets/?proj=Domuztepe+Excavations&person=Elizabeth+Carter retrieves items from the "Domuztepe Excavations" project, associated with the person, Elizabeth Carter. |
|
t-start |
Numeric value |
This parameter filters content by date, with t-start being the earliest date limit. Example: http://opencontext.org/sets/?t-start=-1500&t-end=500 retrieves items from Open Context with dates ranging from 1500 BCE to 500 CE. |
|
t-end |
Numeric value |
This parameter filters content by date, with t-end being the latest date limit. Example (as above): http://opencontext.org/sets/?t-start=-1500&t-end=500 retrieves items from Open Context with dates ranging from 1500 BCE to 500 CE. |
|
tag[] |
Note the square bracket in the tag parameter means that this parameter can take be used multiple times and take multiple values. Values for this parameter are expressed as URL-encoded text |
This parameter filters content by a user-generated tag. Example: http://opencontext.org/sets/?tag%5B%5D=weaving+tools retrieves items from Open Context tagged with "weaving tools". |
|
image |
true |
This parameter filters content by links to images. When the value for this parameter is true, only items associated with images are retrieved. Example: http://opencontext.org/sets/?image=true retrieves items from Open Context associated with images. |
Query results are provided both in summary form and as a list of individual records that match your query criteria. Currently, the user interface of Open Context provides both a summary and list of individual records (in the XHTML representation). To be more specific, the summary form is a list of “facets” that describe the overall characteristics of a query result set. These facets can be retrieved in the Atom Syndication Format or in KML. Individual records of query results can be retrieved in Atom. See table 2 below for examples.
Table 2: Query Result Representations
|
XHTML |
(XHTML version, showing available facets on the left) |
|
Atom (facets / summary) |
http://opencontext.org/sets/facets/.atom
(Atom feed of facets that summarize overall characteristics of the query result set. Geo-spatial facets have locational information expressed in GeoRSS. In this case, because there are no query parameters in this request, this returns a summary of all Open Context content) |
|
JSON (facets / summary) |
http://opencontext.org/sets/facets/.json
(JSON expression of
facets that summarize overall characteristics of the query result
set. Geo-spatial facets have locational information and chronological expressed in
as “geoLat”, “geoLong”, “timeBegin” and “timeEnd” elements.
These can be further processed for use with the Timemap.js library.
|
|
KML (facets / summary) |
http://opencontext.org/sets/facets/.kml
(KML of the geo-spatial facets that summarize overall characteristics of the query result set. In this case, because there are no query parameters in this request, this returns a summary of all Open Context content. Only geo-spatial facets are provided in this representation, since other types of facets don't make visualization sense in applications like Google Earth.) |
|
Atom (individual records) |
http://opencontext.org/sets/.atom
(Atom feed of individual records resulting from a query. Open Search extensions provide a summary of the number of results and feed – paging (implementation of Atom feed paging is forthcoming). All items have location information expressed in GeoRSS. The Atom “link”-element with the attribute “rel='self' ” points to the Atom representation of that specific record and its full ArchaeoML expression. |
|
JSON (individual records and facets) |
http://opencontext.org/sets/.json
(As a convenience for developers who want to create their own search portal for Open Context or a sub-set of Open Context content, we offer a JSON represntation with comprehensive faceted search information and result information. As with the JSON-facets service above, geo-spatial facets have lat / lon point data as well as time range data. These can be further processed for use with the Timemap.js library.) Examples: Bade Museum Website (uses the Open Context JSON service); BoneCommons- Datasets (uses the Open Context JSON service) |
|
Atom Feed of Projects |
http://opencontext.org/projects/.atom
(Open Context provides an Atom+GeoRSS feed of summary descriptions of all projects and collections. The feed is sorted by date of publication in descending order. This feed most closely parallels more familiar applications of the Atom Syndication format.) |
Full Data on Individual Items:
A full XML representation of each location and object item is available. Here are some examples on how to retrieve these representations of Open Context resources:
Table 3: XHTML Web Page and Atom Representations