Web Services (APIs)

Open Context supports content resolution for both item record and search APIs. To request JSON data, include either of the following in the HTTP header of your request:

• Accept: application/json (Usually also valid as JSON-LD)
• Accept: application/vnd.geo+json (Usually also valid as JSON-LD)
• Accept: application/ld+json (Strict JSON-LD)

For individual record items, you can get JSON data by simply adding a ".json" to the end of a record's URL. For example, you can get the JSON for this object: https://staging.opencontext.org/subjects/c4f88b9c-aee0-430a-baad-083f5dfda8fd, with this URL: https://staging.opencontext.org/subjects/c4f88b9c-aee0-430a-baad-083f5dfda8fd.json.

Because JSON-LD has some constraints that make it unsuitable to express complex geospatial features (see note below), Open Context allows you to specifically request strict JSON-LD either through content negotiation or by appending .jsonld to item URLs.

Similarly, adding a ".json" to search URLs also requests JSON data. To do so, add the ".json" just before the quesion-mark ("?") in a search URL. If the URL doesn't have a question-mark, append the ".json" at the end of the URL.

1. Query without a "?" in the URL

   The search URL https://staging.opencontext.org/query/Asia/Turkey/Kenan+Tepe becomes https://staging.opencontext.org/query/Asia/Turkey/Kenan+Tepe.json for a JSON request.

2. Query with a "?" in the URL

   The search URL https://staging.opencontext.org/query/?proj=24-murlo becomes https://staging.opencontext.org/query/.json?proj=24-murlo for a JSON request.

Finally, while Open Context supports CORS (Cross Origin Resource Sharing), in practice some clients may still have trouble accessing JSON data. For these clients, Open Context APIs support JSONP (JSON with "padding") for URLs with a ".json" added as described above. To request JSONP, add a "callback" parameter to your request, as in the examples below:

1. Example (Search/Query Request):

   The plain JSON(-LD) request URL https://staging.opencontext.org/query/Asia/Turkey/Kenan+Tepe.json can be made as a JSONP request like: https://staging.opencontext.org/query/Asia/Turkey/Kenan+Tepe.json?callback=myFunction

2. Example (Item Request):

   The plain JSON(-LD) request URL https://staging.opencontext.org/projects/3585b372-8d2d-436c-9a4c-b5c10fce3ccd.json can be made as a JSONP request like: https://staging.opencontext.org/projects/3585b372-8d2d-436c-9a4c-b5c10fce3ccd.json?callback=oneDoesNotSimply

In Open Context, some items have multiple GeoJSON-LD events. For example, an archaeological site can have multiple episodes of occupation. So a single Open Context record can have multiple GeoJSON-LD features (see example: HTML, GeoJSON-LD).

The Open Context Query API can return GeoJSON-LD features that represent a search result. To simplify matters, only one feature is returned per search result. A "when" object in a feature reflects the item's total time coverage unless the query specified limits on time. If the query limits by time spans, the when object provides a chronology information within the constraints of the query.

By default, the Query API returns GeoJSON-LD features of search results. Search result records come as point features. Two attributes in the JSON data differentiate result record features from facet-region features (see below). These are:

1. Features with an attribute: "category": "oc-api:geo-record"
2. Feature properties with an attribute: "feature-type": "item record"

To limit the GeoJSON-LD response to result records, add a response=geo-record parameter to the query URL (see example).

Open Context returns a few common attributes for result records in the GeoJSON "properties" object. Open Context will add additional attributes to the properties object depending on query filters in the request. For instance, the following search requests animal bones from Ecuador that have a biological taxonomy identification: https://staging.opencontext.org/query/Americas/Ecuador?type=subjects&cat=oc-gen-cat-bio-subj-ecofact---oc-gen-cat-animal-bone&prop=obo-foodon-00001303. GeoJSON result records from that query will have a taxonomic attribute in their properties as shown below:

• "properties": {
• • "id": "#rec-1-of-244200",
  • "feature-type": "item record",
  • "uri": "http://opencontext.org/subjects/72b1adc2-d085-4425-a402-16eab349d8f6",
  • ... more attributes ...
  • "Has taxonomic identifier": ["Lycalopex"]
• }

You can request more attributes to include in the properties of a GeoJSON result record feature. To do so, add the attributes parameter with a comma separated list of descriptive predicates, identified by slug (slugs are included in JSON-LD and are easy to read short-hand identifiers specific to Open Context) or by URI.

1. Animal bones in Ecuador with anatomical identification attribute data: attributes=oc-zoo-has-anat-id
2. Pottery from the Murlo project in Italy with vessel-form attribute data: attributes=24-vessel-form

If you don't know the slugs for attributes you want describing your GeoJSON records, you can request ALL-PROJECT (for all project defined attributes available for an item), ALL-STANDARD-LD (for all "standard" attributes that may be used in multiple projects), or ALL-ATTRIBUTES (for both all project defined and all "standard" attributes).

1. Pottery from the Murlo project in Italy with all project defined attribute data: ALL-PROJECT
2. Pottery from the Murlo project in Italy with all standard attributes used across multiple projects: ALL-STANDARD-LD
3. Pottery from the Murlo project in Italy with all available attributes (both project defined and standard): ALL-ATTRIBUTES

Finally, some clients (especially desktop GIS applications) do a bad job at handling multiple values for property attributes. To work around this problem, you can add the parameter flatten-attributes=1 to the URL requesting GeoJSON records.

Open Context uses a tiling algorithm to hierarchically index geospatial data. This approach allows Open Context to aggregate data at different scales by location. Open Context returns aggregated data as "region facets" that can be visualized in a map interface as square polygons. By default the query API returns region facets. Two attributes in the JSON data differentiate result record features (see above) from facet-region features. These are:

1. Features with an attribute: "category": "oc-api:geo-facet"
2. Feature properties with an attribute: "feature-type": "discovery region (facet)"

To limit the GeoJSON-LD response to facet regions, add a response=geo-facet parameter to the query URL (see example).

Last, you can change the level of aggregation in the facet regions with the geodeep parameter. The maximum value is 20, corresponding to a Web mapping zoom level of 20. Below are two examples with different levels of aggregation:

1. More aggregated (coarse) data at geodeep=7, presented in: HTML (with map visualization) or GeoJSON-LD
2. Less aggregated (fine-grain) data at geodeep=11, presented in: HTML (with map visualization) or GeoJSON-LD

Adding this query parameter with a URL encoded search term requests a full-text search. This works similarly to familiar text searches elsewhere on the Web, and can be combined with other search parameters. Here is an example text search for the term "bucchero".

Adding this query parameter with a URL encoded URI requests records that link (via any attribute or relation predicate) to a URI-indentified entity defined by a data source, vocabulary or ontology outside of Open Context.

For example, this search, https://staging.opencontext.org/query/?obj=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FUBERON_0000979, finds all records associated with the UBERON concept for the bone element tibia, identified by this URI: http://purl.obolibrary.org/obo/UBERON_0000979. This example works similarly to a SPARQL query formulated like:

This query parameter requests a filter defined by a geospatial bounding box for the location of discovery or description. The bounding box is expressed as comma sperated values of coordinates using the WGS84 (typical for Web mapping) decimal degrees. The order of coordinates follows the GeoJSON pattern of (x,y) (Longitude, Latitude). The first pair of coordinates defines the lower-left (south-west) corner of the bounding box, with the second pair of coordinates defines the top-right (north-east) corner. An invalid bounding box will be ignored as a search filter but will return a notice in the oc-api:active-filters of the JSON-LD response.

Bounding Box search examples include:

1. Filtering for a region in the south-east of the United States: -87.19 Longitude, 21.29 Latitude (south-west corner) to -73.48 Longitude, 34.60 Latidude (north-east corner)
2. You can use the double pipe characters ("||") for Boolean "OR" searches of multiple regions, as in this example: 31.37,C34.31,35.42,C35.96 (roughly Cyprus) OR 31.86,35.89,34.53,36.97 (roughly Cilicia in Turkey)

These parameters filter a request by the general date ranges of the formation, use, and/or life of items described in the search results. The allevent-start parameter defines the earliest date to include in search results, while the allevent-stop defines the latest date to include in search results. With these parameters, use integer dates (negative values for dates BCE) and positive values for dates CE.

Some items, such as archaeological sites, may have multiple date ranges (a site may have multiple episodes of occupation and use). In these cases, Open Context's query results will include records that have date ranges falling within the allevent-start and allevent-stop limits, even if the records also have date ranges that fall outside of these limits.

Date range search examples include:

1. Filtering for sites in the United States that have occupation / use components that date before 7500 BCE: allevent-start=-7500
2. Filtering for cattle bones dating between 15000 BCE and 4000 BCE: allevent-start=-12000&allevent-stop=-4000

Adding this query parameter and value adds a special filter for interacting with data in the Digital Index of North American Archaeology (DINAA) project. The query filters for DINAA records cross-referenced with URI identified resources curated by other online collections. Click here to view cross-referenced records in DINAA.

Adding this query parameter and value filters records for different types of identifiers, including DOIs, ARKs, ORCIDs, and Open Context URIs and UUIDs. Open Context will evaluate query with different variants of expressing an identifer. For example, the identifier "doi:10.6078/M77P8W98" can be expressed as:

• doi:10.6078/M77P8W98
• https://doi.org/10.6078/M77P8W98, the current preferred URL expression for a DOI.
• http://doi.org/10.6078/M77P8W98, not secured (not preferred) URL expression for a DOI.
• https://dx.doi.org/10.6078/M77P8W98, an older URL expression for a DOI.
• http://dx.doi.org/10.6078/M77P8W98, an older URL expression for a DOI, without an encrypted request.

A search for any one of the above ID varients will retrieve the same record.

Total number of results found in the search.

The Query API returns summary time span information for the set of results obtained from a query. Time intervals describe general date ranges relevant to the formation, use, and/or life of items described in the search results. The API expresses the date information as ISO 8601 defined string values in the start and stop limits (the same kind of expression used in GeoJSON "when" objects). The dc-terms:temporal key provides the same time-span information in a manner consistent with Pelagios project (see documentation here) patterns.

The Query API returns links to page through the list of query result records. Paging links are provided for both HTML and JSON versions as follows:

1. first, first page
2. previous, previous page
3. next, next page
4. last, last page

In addition to paging, the Query API provides details about the start of the index number of the current page's search results. "startIndex": 0 is the beginning of the list of results. As one pages through the search results, the startIndex increases. You can change the number of results returned per page with the rows parameter. Open Context defaults to 20 records per page and this can be increased to 1000 with rows=1000.

The Query API provides a list of the filters currently constraining the the search results. The API provides some descriptive information for each filter, including links indicated as oc-api:remove or oc-api:remove-json that can be followed to remove that particular filtering constraint.

The Query API provides a list of ways one can add an additional full-text search constraint to any search constraints already in place. The API provides a template for composing URLs to request full-text searches in the oc-api:template or oc-api:template-json keys. Substitute the {SearchTerm} in those URLs with the URL encoded text of your search term(s).

These are hierarchically organized time-spans for dates in the past. Since the algorithm (described here) used to compute these facets needs a fixed reference point, the latest possible date in these time-spans is the year 2000 (CE). The start and stop attribute keys describe dates in years BCE / CE, with BCE dates as negative values. In way that's similar to the geo-region facets described above, you can control the level of chronological aggregation to your requests by adding the chronodeep query parameter to request URLs.

1. More aggregated (coarse) chronology data at chronodeep=16, the default level, as JSON-LD
2. Less aggregated (fine-grain) chronology data at chronodeep=32, the maximum precision, as JSON-LD

Usually, the facet count will be the same as the number of records returned if you execute the search option, but that is not always the case for chronological facets. Items in Open Context (especially archaeological sites) can have multiple time spans of use. A chronological facet count reflects the number of times a particular time-span bucket is filled. A single record of an archaeological site can fill multiple time-span buckets. This sometimes makes facet counts for time-spans a close approximation rather than an exact match of filtering by a particular time-span.

These are hierarchically organized descriptive predicates and controlled vocabulary concepts that Open Context exposes to guide searches. Diferent metadata facets have some descriptive information and come with lists of options that can be used to further filter the search. There are four types of option lists for faceted searching:

1. oc-api:has-id-options: options in this list are concepts or other named entities identified by URIs. The rdfs:isDefinedBy predicate indicates the URI for the concept defining the particular search filter.
2. oc-api:has-boolean-options: these options describe boolean attributes.
3. oc-api:has-integer-options: these options describe integer attributes for records. Selecting one of these options will request integer numeric range data associated with the option.
4. oc-api:has-float-options: these options describe floating point (decimal) attributes for records. Selecting one of these options will request numeric range data associated with the option.
5. oc-api:has-date-options: these options describe records with (recent) calendric date information. Selecting one of these options will request calendric range data associated with the option.
6. oc-api:has-text-options: these options include fields that describe records with unstructured text (not controlled vocabularies). Selecting one of these options will request a full-text search template for this field.

These facets summarize the current set of search results according to a given numeric property. The minimum value (oc-api:min) and the maximum value (oc-api:max) give the total range of values for the records defined by the current search filters. In addition, the oc-api:has-range-options list quantifies the number of records in different numeric ranges. These can be visualized to make histograms of summarizing all of the records for a search according to this numeric property. The example below describes two numeric range options:

• "oc-api:has-range-options": [
• • {
  • • "id": "https://staging.opencontext.org/query/?prop=24-bd---%5B3.79+TO+10.850999999999999+%5D&proj=24-murlo",
    • "json": "https://staging.opencontext.org/query/.json?prop=24-bd---%5B3.79+TO+10.850999999999999+%5D&proj=24-murlo",
    • "label": "3.79",
    • "count": 68,
    • "oc-api:min": 3.79,
    • "oc-api:max": 10.850999999999999
  • },
  • {
  • • "id": "https://staging.opencontext.org/query/?prop=24-bd---%5B10.850999999999999+TO+17.912+%5D&proj=24-murlo",
    • "json": "https://staging.opencontext.org/query/.json?prop=24-bd---%5B10.850999999999999+TO+17.912+%5D&proj=24-murlo",
    • "label": "10.851",
    • "count": 124,
    • "oc-api:min": 10.850999999999999,
    • "oc-api:max": 17.912
  • }, ...
• ]

Open Context simply uses Solr query syntax for numeric queries. In the first example above, the query term for the numeric range filter is [3.79 TO 10.850999999999999] (URL-encoded). You can substitute that term with any valid Solr numeric query.

These facets summarize the current set of search results according to a given calendric property. They work in a very similar way to the numeric facets described above. One can also use valid Solr syntax to query against calendric properties.