Open Context API/Web-Services Documentation
In addition to the Concepts and Technology pages, this page provides extensive information about the nuts and bolts of how Open Context works. It is not necessary for all Open Context authors and users to understand the system at this level of detail, but we provide it here for those who are interested.
Open Context provides 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). 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). Query results 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, with news items from journalists or bloggers, or even displayed in personal profiles in Facebook.
You can make requests 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.
Table 1: Query Parameters to Retrieve Sets of Items
| Parameter | Possible Values | Description |
|---|---|---|
| (Context path) | Slash separated values of URL-encoded text. Use two pipe characers ('||') for OR terms. |
This represents spatial containment “paths” with larger locations and objects containing nested (child) locations and objects. Examples:
|
| 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. Examples:
|
| 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. Examples:
|
| proj | URL-encoded text. Use two pipe characers ('||') for OR terms. |
This parameter filters by the names of projects / collections. Limit of 128 characters. Examples:
|
| cat | URL-encoded text |
This parameter filters content by its general category (“Animal Bone”, “Small Find”, etc.) Examples:
|
| taxa[] | URL-encoded text. Use this parameter to query for desciptive properties and hierarchic taxonomies. These properties can be simple variable-value pairs, or deeper hierarchical taxonomies with nodes seperated by two colons ('::'). Numeric values can be proceeded by 'URL-encoded '>', '>=', '<', or '<=' to make range queries.) Use two pipe characters ('||') for OR terms. |
This parameter is for querying the descriptive properties and hierarchic taxonomies used by data contributors. For the most part, descriptive properties in Open Context have a very "flat" hierarchy, and are simply variable / value pairs, expressed as 'taxa[]={variable}::{value}', where 2 colons ('::') seperate the variable from the value. A deeper taxonomic tree can be queried as follows: 'taxa[]={node}::{node}::{node}'. Examples:
|
| rel[] | URL-encoded text. Use this parameter to query Open Context using URI-identified concepts. Use two pipe characters ('||') for OR terms. |
This parameter is for querying Open Context using URI-identified concepts. Please note, Open Context does not (yet) have a triple-store nor is this parameter used for SPARQL. This parameter is simply used to query Open Context for subjects (URI-identifed documents describing individual locations and objects) based on very simple relations to URI identified concepts. In 'Linked Data' terms, the items returned in a query are the 'subjects' while the 'predicate' and 'object' (or 'target') are expressed as URI identified concepts seperated by 2 colons ('::') according to this template: 'rel[]={URI identified predicate}::{URI identified object}'. Examples:
|
| targURI | URL-encoded text. Use this parameter to query Open Context using URI-identified concepts of the object / target entities of a relationship. Use two pipe characters ('||') for OR terms. |
This parameter is for querying Open Context using URI-identified concepts where the predicate relationship is not known or does not matter. It works according to this template: 'targURI={URI identified object}'. Examples:
|
| (DEPRECATED) prop[*] | URL-encoded text(variable names within the square brackets) |
NOTE: This parameter is deprecated. For the time being, Open Context will still resolve queries using this parameter, but the preferred parameter for querying descriptive properties is "taxa[]", described above. 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. Examples:
|
| person | URL-encoded text |
This parameter filters content by individual people and organizations associated with the content (authors, observers, analysts, etc.). Use two pipe characers ('||') for OR terms. Examples:
|
| t-start | Numeric value |
This parameter filters content by date, with t-start being the earliest date limit. Examples:
|
| t-end | Numeric value |
This parameter filters content by date, with t-end being the latest date limit. Examples:
|
| 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. Examples:
|
| diary | true |
This parameter filters content by links to documents (diaries, logs, or other narrative documentation). When the value for this parameter is true, only items associated with documents are retrieved. Examples:
|
| sort | "label", "cat", "context", "proj", "created", "updated". (defaults to ascending order. ':desc' changes to descending order) |
This parameter changes the sort-order of search result items retrieved from Open Context. By default, Open Context sorts search results by "interestingness". More interesting items have more description and more links to associated media (images, documents, etc.). By default, these more richly described items are ranked higher in searches. To change sort order, add the "sort" parameter to queries as follows: Examples: |
| recs | Positive integer values, ranging from 1 to 50 |
This parameter changes the number of items displayed from a query. By default, Open Context shows 10 items from queries on locations and objects, and 18 thumbnails for image searches. Note: many queries return many more results than can be displayed at once. Use the "page" parameter described below to page through long sets of query results. Examples:
|
| page | Positive integer values |
Open Context often returns large numbers of items from queries. Because it is not feasible to display hundreds or thousands of results at once, large sets of results are delivered in different "pages". Open Context returns search results using the Atom Syndication Format (see below). This Atom representation has link elements pointing to different pages of search results. Examples:
|
Faceted Search Results and Representations
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, JSON or in KML. Individual records of query results can be retrieved in Atom, JSON, or KML. See table 2 below for examples.
Table 2: Query Result Representations
| Representation | Description and Example |
|---|---|
| XHTML |
XHTML version, showing available facets on the left Examples: |
| Atom (facets / summarized query results) |
Atom feed of facets that summarize overall characteristics of the query result set. Feed-entries have different facets and facet counts, where <link> elements have links to futher filter the query according to the facet expressed in the entry. Geo-spatial facets have locational information expressed in GeoRSS. Examples: |
| JSON (facets / summarized query results) |
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. Examples: |
| KML (facets / summarized query results) |
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. Examples: |
| Atom (individual search result records) |
Atom feed of individual records resulting from a query. Open Search extensions provide a summary of the number of results and feed – paging provides links to other pages of a search result set. 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 representation. Examples: |
| JSON (individual search result records) |
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 individual search result items. 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. Note: Open context also offers a JSON/P ("JSON with Padding") representation. JSON/P is a useful workaround for "cross domain problems". It lets third-parties create web-pages using Open Context data without having those data first go to their server, and then to clients. To make JSON/P requests, simply add the parameter "callback" with its value set to the name of the function that you want to use to "pad" the JSON data. Plain JSON Examples:
JSON/P Examples:
|
| GeoJSON (spatial context facets) |
Open Context offers a GeoJSON representation of geospatial metadata facets. GeoJSON is widely supported by many mapping libraries and is an increasingly popular format for expressing spatial data. The Open Context GeoJSON service can also be accessed as JSON/P data. To make JSON/P requests, simply add the parameter "callback" with its value set to the name of the function that you want to use to "pad" the JSON data. Plain GeoJSON Examples:
(Geo)JSON/P Example:
|
Representations of Individual Items / Records
Open Context offers multiple representations of individual data records / items in XHTML, Atom, and ArchaeoML-XML. The ArchaeoML-XML representation is currently the richest and most comprehesive expression of Open Context data. We are currently also developing RDF representations representation that include mappings to the CIDOC-CRM. Here are some examples on how to retrieve these representations of Open Context resources:
Table 3: Item Representations
| Representation | Description and Examples |
|---|---|
| XHTML + RDFa |
This representation is given for rendering content in web browsers. Some linked data information (particularly Dublin Core metadata) is expressed in RDFa mark-up in this representation. Examples:
|
| Atom |
An Atom <entry> representation provides some simple metadata about each Open Context resource (data items / records). Examples:
|
| ArchaeoML (XML) |
Open Context uses ArchaeoML-XML as its internal data structure. Making ArchaeoML representations publicly available makes Open Context data full portable. ArchaeoML representations are currently the richest and most comprehesive expressions of Open Context data. We use GitHub for version control of ArchaeoML documents. For long term preservation, the California Digital Library archives these data. Examples:
|
| RDF |
We are currently developing RDF representations (in RDF/XML and RDF/Turtle) for richer and easier to parse expression of linked data than in the XHTML+RDFa format. Examples:
|
Other Web-Services
Open Context also has a variety of other Web services to share updates, use metrics, metadata, and assist in linked data projects. These services are listed in table 4 below.
Table 4: Other Web Services
| Service | Description and Examples |
|---|---|
OAI-PMH
|
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) |
| Atom Feed of Projects |
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. Examples: |
| Atom Feed of All Content |
Open Context provides this update-time sorted (most recent first) feed provides a comprehensive list of all Open Context content. Digital archives can use this paged feed to retrieve all resources relevant to data curation from Open Context. Examples: |
| Pelagios Annotations (RDF as N-Triples) |
Open Context annotates relevant data with geographic place references using the Pleiades and GeoNames gazetteers. These annotations conform to the requirements of the Pelagios Project. We offer a RDF data-dump of these annotations as a fully public domain open dataset (CC-Zero). Examples:
|
Entity Reconciliation Service (IN TESTING)
Open Context is currently alpha-testing an entity reconciliation service (see this definition from Freebase). One can use Open Context's service to look up Web identifiers for certain concepts linked by Open Context. By doing so, you can precisely relate key concepts and entities in a dataset to concepts published on the Web. Currently, Open Context's reconciliation service only supports look-ups to find Encyclopedia of Life (EOL) identifiers for biological taxa. However, we will shortly offer additional options for reconciling terms against other bio-informatics vocabularies. We hope to support reconcilation against certain concepts used to describe material culture as well.
Unless you are a programmer, it is easiest to use Google Refine to use this reconciliation service. Google Refine is an open source data review and editing tool that also has powerful features to use Web-APIs. It can be used to work with Open Context's reconciliation service as described below:
Procedure (in Google Refine)
- Click on the column with biological taxa terms to select it. Create a column for the EOL identifiers of taxa by Add Column By Fetching URLs...
- In the expression field, write:
"http://opencontext.org/sets/reconciliation/.json?rel=http%3A%2F%2Fpurl.org%2FNET%2Fbiol%2Fns%23term_hasTaxonomy&rq=" + escape(value, "url")The adove expression will get a list of possible EOL identifiers for biological taxa, ranked from most commonly used to the least commonly used. - Completing the step above will populate this new column with JSON data (a "machine-readable" data format) from Open Context. You'll need to process these results further with the Edit Cells > Transform... command.
- In the expression field, write:
value.parseJson()["reconResults"][0]["uri"]The above expression generates a link to an EOL Web page representing the mostly likely match to the taxonomic term in your dataset. - Check the results! This is a semi-automated approach. You'll need to check to make sure the results make sense and reference appropriate EOL pages.
One can also take advantage of Open Context's powerful index and add additional filters and query parameters to further constrain the search for relevant identifers. For example, a query to get a Web identifier for a biological taxon associated with the term "sheep" can be limited by a geographic bounding box as follows:
Please note! This reconciliation service needs testing and evaluation. We welcome feed-back to improve our efforts (contact the Editor).
