Project

General

Profile

Actions
History

Archive » Api »

API 0.2 (unstable)

The API basically can be accessed through two methods: Either from the user interface of an OpenAtlas application or, if the settings will allow it, from another application.

Please also refer to the SwaggerHub documentation: https://app.swaggerhub.com/apis-docs/ctot-nondef/OpenAtlas/0.2

Endpoints

Entity/Entities Endpoints

These endpoints can provide full information about one or more entities. The output format is the Linked Place Format(LPF). Alternativly there is a simple GeoJSON format and multiple RDFs, derived from the LPF, available.

/api/0.2/entity/{id}

Retrieves a representations of an entity through the ID.

/api/0.2/class/{cidoc_class_code}

Retrieves a json with a list of entities based on their CIDOC CRM class code. The outpout contains a results and pagination key. All in OpenAtlas available codes can be found under OpenAtlas and CIDOC CRM. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/code/{view_name}

Retrieves a json with a list of entities based on their OpenAtlas view name. Available categories can be found at OpenAtlas and CIDOC CRM. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/system_class/{system_class}

Retrieves a json with a list of entities based on their OpenAtlas system class. Available categories can be found at OpenAtlas and CIDOC CRM. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/query/

With the query endpoint, one can combine the three endpoints above in a single query. Each request has to be a new parameter. Possible parameters are:

  • ?entities={id}
  • ?classes={cidoc_class_code} deprecated
  • ?codes={view_name} deprecated
  • ?system_classes={system_class} deprecated

For more details of the different queries please consult the associated section. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/latest/{1-100}

Retrieves the latest entries made in the OpenAtlas database. The number represents the amount of entities retrieved. /latest can be any number between and including 1 and 100.

/api/0.2/entities_linked_to_entity/{id}

Retrieves a list of entities, which are linked to the entity with the given id. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/type_entities/{id}

Retrieves a list of entities based on their OpenAtlas type. A possible id can be obtained for example by the type_tree or node_overview endpoint. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

/api/0.2/type_entities_all/{id}

Retrieves a list of entities based on their OpenAtlas type. This also includes all entities, which are connected to an subtype. A possible id can be obtained for example by the type_tree or node_overview endpoint. The result can be filtered, ordered and manipulated through different parameters. By default results are orderd alphabetically and 20 entities are shown.

Nodes Endpoints

/api/0.2/node_entities/{id} deprecated

Retrieves a JSON list of entities names, IDs and URLs, based on their OpenAtlas type. Be aware that "Historical Place" and "Administrative Units" cannot be retrieved by this.

/api/0.2/node_entities_all/{id} deprecated

Retrieves a JSON list of entities names, IDs and URLs, based on their OpenAtlas type. This also includes all subtypes of the given type id. Be aware that "Historical Place" and "Administrative Units" cannot be retrieved by this.

/api/0.2/subunit/{id} deprecated

Retrieves a JSON list of entities names, IDs and URLs, from the first layer of subunits from the given entity ID.

/api/0.2/subunit_hierarchy/{id} deprecated

Retrieves a JSON list of entities names, IDs and URLs, of all subunits from the given entity ID.

/api/0.2/type_tree/

Retrieves a detailed JSONlist of all OpenAtlas types. This includes also includes a list of childrens of a type

/api/0.2/node_overview/ deprecated

Retrieves a JSON list of all OpenAtlas types sorted by custom, places, standard and value.

Content Endpoints

/api/0.2/classes

Provides a list of all available system classes, their CIDOC CRM mapping, which view they belong, which icon is used and the English name

/api/0.2/content

Retrieves a json of the content (Intro, Legal Notice, Contact and the size for processed images) from the OpenAtlas instance. The language can be chosen with the lang parameter (en or de).

/api/0.2/geometric_entities/

Retrieves a list of all selected geometries in the database in a standard GeoJSON format. This endpoint should be used for map overviews.

/api/0.2/system_class_count/

Retrieves a list of how many entities, a system class has.

Image Endpoint

/api/display/{id}

Provides the image of the requested ID. Be aware, the image will only be displayed if:

  • Request comes from a logged-in user
  • API public setting is set on AND the image has a Licence

Parameters

Not all endpoints support all parameters. Also, some endpoints has additional unique parameter options, which are described at their section.

path\parameter type_id format page sort column limit filter first last show count download lang geometry image_size
entity x x x
code x x x x x x x x x x x x
system_class x x x x x x x x x x x x
entities_linked_to_entity x x x x x x x x x x x x
type_entities x x x x x x x x x x x x
type_entities_all x x x x x x x x x x x x
class x x x x x x x x x x x x
latest x x x x x x x x x x x x
query x x x x x x x x x x x x
node_entities x x
node_entities_all x x
subunit x x
subunit_hierarchy x x
type_tree x x
node_overview x x
geometric_entities x x x
content x x
classes
system_class_count
display x

Sort

<'asc', 'desc'>

The sort parameter controls the order of the results. These can be either ascending (asc) or descending (desc). To use this feature add the parameter:
?sort=<'asc','desc'>

Validation

If multiple sort parameter are used, the first valid sort input will be used.
It does not matter if the words are uppercase or lowercase (i.e. DeSc or aSC), but the query only takes asc or desc as valid input. If no valid input is provided, the result is orders ASC.

Column

<'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'>

The column parameter declares which columns in the table are sorted with the sort parameter.

?column=<'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'>

Validation

If multiple column parameter are used, a list is created, by the order in which the parameters are given (i.e. ?column=name&column=description&column=id will order by name, description and id).
It does not matter if the words are uppercase or lowercase (i.e. Name, ID, DeScrIPtioN or Class_Code). If no valid input is provided, the results are ordered by name.

Limit

<number>

The limit parameter declares how many results will returned.

?limit=<number>

Validation

If multiple limit parameter are used, the first valid limit input will be used. Limit only take positive numbers.

Filtering deprecated

<=, !=, <, <=, >, >=, LIKE, IN, AND, OR, AND NOT, OR NOT>

The filter parameter is used to specify which entries should return.

?filter=<XXX>

Validation

Filter takes a lot of different parameters in various forms. Filter values need to be separated by |.
  1. First value has to be a concatenation operator: 'and': 'AND', 'or': 'OR', 'onot': 'OR NOT', 'anot': 'AND NOT'.
  2. Second value has to be the effected column: 'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'.
  3. Third value has to be a logical operator: 'eq': '=', 'ne': '!=', 'lt': '<', 'le': '<=', 'gt': '>', 'ge': '>=', 'like': 'LIKE',
  4. Fourth value has to be the search term. If the 'in' operator is selected, then the search term has to be in brackets and separated by commas.

Please note, that the filter values will translate directly in SQL. For example: 

?filter=and|name|like|Ach&filter=or|id|gt|5432

will result in
AND e.name LIKE %%Ach%% OR e.id > 5432


?filter=or|id|gt|150&filter=anot|id|ne|200 
?filter=and|name|like|Ach

Pagination (page / first / last)

first=<id> OR last=<id> OR page=<int>

The page parameter will take any number as page number and provides the entities of this page.
The first parameter takes IDs and will show every entity after and including the named ID.
The last parameter takes IDs and will show every entity after the named ID.

?page=<int>

?first=<id>

?last=<id>

Validation

Page, first and last will only take numbers. First and last has to be a valid ID. The table will be sorted AND filtered before the pagination comes in place. 

?page=4
?last=220
?first=219

Show/Hide Types

<'when', 'types', 'relations', 'names', 'links', 'geometry', 'depictions', 'none'>

The show parameter will take in the key values of a json. If no value is given, every key will be filled. If a value is given, it only will show the types which are committed. If the parameter contains none, no additional keys/values will be shown. This will only work with the Linked Places Format.

?show=<'when', 'types', 'relations', 'names', 'links', 'geometry', 'depictions', 'none'>

Validation

For each value, a new parameter has to be set. The value will be matched against a list of keywords, so wrong input will be ignored.

?show=when
?show=types
?show=types&show=when
?show=none

Format

lp, geojson, pretty-xml, n3, turtle, nt, xml

With the format parameter, the output format of an entity representation can be selected. lp stands for Linked Places Format, which is the standard selection. For information on other formats, please confer API Output Formats

?format=<lp, geojson, pretty-xml, n3, turtle, nt, xml>

Validation

Only the last format parameter counts as valid input. This parameter is not case-sensitive.

?format=lp
?format=geojson
?show=n3

Type ID

<int>

The whole search query will be filtered by this Type ID. Multiple type_id parameters are valid and are connected with a logical OR connection.

?type_id=<id>

Validation

type_id only takes a valid type ID.

?type_id=<int>

Count

<>

Returns a json with a number of the total count of the included entities.

?count

Validation

Only count will trigger the function. Count can have any numbers assigned to it, which makes no difference.

?count

Download

<>

Will trigger the download of the result of the request path.

?download

Validation

Only download will trigger the function. Download can have anything assigned to it, but this will be discarded.

?download

Lang (Language)

<'en', 'de'>

Select the language, which content will be displayed.

?lang

Validation

Default value is None, which means the default language of the OpenAtlas instance is taken.

?lang
?lang=en
?lang=DE

Geometry

   gisAll, gisPointAll, gisPointSupers, gisPointSubs, gisPointSibling, gisLineAll, gisPolygonAll

Filter, which geometric entities will be retrieved through /geometric_entities. Multiple geometry parameters are valid. Be aware, this parameter is case-sensitive!

?geometry

Validation

The default value is gisAll. Be aware, this parameter is case-sensitive!

?geometry=gisPointSupers
?geometry=gisPolygonAll

Updated by Bernhard Koschiček-Krombholz almost 2 years ago · 21 revisions

Also available in: PDF HTML TXT