h1. API 0.3 (stable)

{{toc}}

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.

h1. Endpoints

h2. Entity/Entities Endpoints

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

h3. /api/0.3/entity/{id}

Retrieves a representation of an entity through the ID.

h3. /api/0.3/cidoc_class/{cidoc_class_code}

Retrieves a json with a list of entities based on their CIDOC CRM class code. The output 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 ordered alphabetically, and 20 entities are shown.

h3. /api/0.3/view_class/{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 ordered alphabetically and 20 entities are shown.

h3. /api/0.3/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 ordered alphabetically and 20 entities are shown.

h3. /api/0.3/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}
* ?cidoc_classes={cidoc_class_code}
* ?view_classes={view_name}
* ?system_classes={system_class}

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 ordered alphabetically, and 20 entities are shown.

h3. /api/0.3/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. 


h3. /api/0.3/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 ordered alphabetically and 20 entities are shown.


h3. /api/0.3/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 ordered alphabetically and 20 entities are shown.

h3. /api/0.3/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 ordered alphabetically, and 20 entities are shown.

h2. Type Endpoints

h3. /api/0.3/type_tree/

Retrieves a detailed JSON list of all OpenAtlas types. This includes also includes a list of children of a type

h3. /api/0.3/type_overview/

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

h2. Subunit Endpoints

h3. /api/0.3/subunits/{id}

Takes only a valid place (E18) ID. Retrieves a list of the given place and all of its subunits. This endpoint provides a special [[Thanados Format]]. With the *format=xml* parameter, an XML can be created,

h2. Content Endpoints

h3. /api/0.3/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

h3. /api/0.3/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).

h3. /api/0.3/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. 

h3. /api/0.3/system_class_count/

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

h2. Image Endpoint

h3. /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*

h1. 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 |_.search|_.first |_.last |_.show |_.count |_.download |_.lang |_.geometry |_.image_size|_.export|
| entity |  | x |  |  |  |  |  |  |  | x |  | x |  |  |  | x |
| code | x | 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 |  |  |  | x |
| entities_linked_to_entity| x | 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 |  |  |  | x |
| type_entities_all| x | 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 |  |  |  | x |
| latest | x | 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 |  |  |  | x |
| type_entities |  |  |  |  |  |  |  |  |  |  | x | x |  |  |  | x |
| type_entities_all|  |  |   |  |  |  |  |  |  |  | x | 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 |  |


h2. Sort

<pre>
<'asc', 'desc'>
</pre>
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:
 <pre>?sort=<'asc','desc'></pre>

h3. 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.

h2. Column

<pre>
<'id', 'name', 'cidoc_class', 'system_class'>
</pre>

The _column_  parameter declares which columns in the table are sorted with the _sort_ parameter.

<pre>?column=<'id', 'name', 'cidoc_class', 'system_class'></pre>

h3. 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=id will order by name and then by 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.

h2. Limit

<pre>
<number>
</pre>

The _limit_ parameter declares how many results will return. _limit=0_ will return all entities. 

<pre>?limit=<number></pre>

h3. Validation

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

h2. Search

The search parameter provides a tool to filter and search the data with logical operators.

Search parameter:
<pre>
?search={}
</pre>

Logical operators: 
These are not mandatory. _or _ is the standard value. 
<pre>
 and, or 
</pre> 

Compare operators:
<pre>
equal, notEqual, like(1), greaterThan(2), greaterThanEqual(2), lesserThan(2), lesserThanEqual(2)
(1) Only string categories
(2) Only beginFrom, beginTo, endFrom, endTo, valueTypeID
</pre>

Filterable categories:
<pre>
entityName, entityDescription, entityAliases, entityCidocClass, entitySystemClass, entityID, typeID, valueTypeID, typeIDWithSubs, typeName, beginFrom, beginTo, endFrom, endTo, relationToID
</pre>

h3. Usage

The search parameter takes a JSON as value. A key has to be a *filterable category* followed by a list/array. This list need to have again JSON values as items. There can be multiple search parameters. E.g:

<pre>
?search={"typeID":[{"operator":"equal","values":[123456]}], "typeName":[{"operator":"like","values":["Chain", "Bracelet", "Amule"],"logicalOperator":"and"}]}&search={"typeName":[{"operator":"equal","values":["Gold"]}], "beginFrom":[{"operator":"lesserThan","values":["0850-05-12"],"logicalOperator":"and"}]}
</pre>

h4. Logical connections

Every JSON in a search parameter field is logical connected with AND. E.g:

<pre>
?search={A:[{X}, {Y}], B: [M]} => Entities containing A(X and Y) and B(M) 
</pre> 

Each search parameter is logical connected with OR. E.g:

<pre>
?search={A:[{X}, {Y}]}&search={A:[{M}]} => Entities containing A(X and Y) or A(M)
</pre> 

h4. Queries

Within the list of a key, there are multiple queries possible. A query contains a compare operator, the values to be searched and a logical operator, how the values should be handled. E.g:

<pre>
{"operator":"equal","values":[123456],"logicalOperator":"or"}
{"operator":"notEqual","values":["string", "otherString"],"logicalOperator":"and"}
{"operator":"lesserThan","values":["0850-05-12"],"logicalOperator":"and"}
{"operator":"like","values":["Gol", "Amul"],"logicalOperator":"and"}
</pre>

h4. values

Values has to be a list of items. The items can be either a string, an integer or a tuple (see Note). Strings need to be marked with "" or '', while integers doesn't allow this.  

*Note*: the category valueTypeID can search for values of a type ID. But it takes one or more two valued Tuple as list entry: (x,y). x is the type id and y is the searched value. This can be an int or a float. E.g:

<pre>
{"operator":"lesserThan","values":[(3142,543.3)],"logicalOperator":"and"}
</pre>

h4. Compare operators

The compare operators work like the mathematical operators. equal x=y, notEqual x!=y, greaterThan x>y , greaterThanEqual x>=y, lesserThan x<y, lesserThanEqual x<=y. The like operator searches for occurrence of the string, so a match can also occur in the middle of a word. 

h4. Explained Example:

With the example above, we can textualize the outcome: 
<pre>
?search={"typeID":[{"operator":"equal","values":[123456],"logicalOperator":"or"}, "typeName":[{"operator":"notEqual","values":["Chain", "Burial object"],"logicalOperator":"and"]}&search={"typeName":[{"operator":"like","values":["Gol"],"logicalOperator":"or"}]}
</pre>

Get entities which has the typeID 123456 AND NOT the types called "Chain" AND "Burial object", OR all entities which has the typeName with "Gold" in the type name.

h2. Pagination (page / first / last)

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

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. 

<pre>?page=<int></pre>
<pre>?first=<id></pre>
<pre>?last=<id></pre>

h3. 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. 
<pre>
?page=4
?last=220
?first=219
</pre>

h2. Show/Hide Types

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

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.

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

h3. 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.

<pre>
?show=when
?show=types
?show=types&show=when
?show=none
</pre>

h2. Show/Hide Relations by Property Code

<pre>
<'P2', 'P67', 'P53', 'OA7', ...>
</pre>

The _relation_type_ parameter will take the property code from CIDOC CRM (P) and the OpenAtlas codes (OA) as values. The *relation* json field from the Linked Places Format will only show relations with the given code. This can significantly decrease the payload.  

h3. Validation

For each value, a new parameter has to be set. The value will be matched against the list of possible property codes. Wrong input will be ignored.

<pre>
?relation_type=P2
?relation_type=P67
?relation_type=2&relation_type=OA7
</pre>


h2. Format

<pre>
lp, geojson, pretty-xml, n3, turtle, nt, xml
</pre>

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]]

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

h3. Validation

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

<pre>
?format=lp
?format=geojson
?show=n3
</pre>


h2. Type ID 

<pre>
<int>
</pre>

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. 

<pre>?type_id=<id></pre>

h3. Validation

_type_id_ only takes a valid type ID. 

<pre>
?type_id=<int>
</pre>

h2. Count

<pre>
<>
</pre>

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

<pre>?count</pre>

h3. Validation

Only _count_ will trigger the function. Count can have any numbers assigned to it, which makes no difference. 
 
<pre>
?count
</pre>

h2. Download

<pre>
<>
</pre>

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

<pre>?download</pre>

h3. Validation

Only _download_ will trigger the function. Download can have anything assigned to it, but this will be discarded. 
 
<pre>
?download
</pre>

h2. Lang (Language)

<pre>
<'en', 'de'>
</pre>

Select the language, which content will be displayed. 

<pre>?lang</pre>

h3. Validation

Default value is None, which means the default language of the OpenAtlas instance is taken. 
 
<pre>
?lang
?lang=en
?lang=DE
</pre>

h2. Geometry

<pre>
   gisAll, gisPointAll, gisPointSupers, gisPointSubs, gisPointSibling, gisLineAll, gisPolygonAll
</pre>

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

<pre>?geometry</pre>

h3. Validation

The default value is _gisAll_. Be aware, this parameter is case-sensitive!
 
<pre>
?geometry=gisPointSupers
?geometry=gisPolygonAll
</pre>

h2. Export

<pre>
   csv, csvNetwork
</pre>

Export the result in the given format as download. *csv* is one single CSV file of the result. *csvNetwork* are multiple CSV files, especially used for network analysis. So there are for each system class a CSV, describing the entities, a link.csv where the links between the entities are shown and a geometry.csv containing the geometries. 

<pre>?export</pre>

h3. Validation

 
<pre>
?export=csv
?export=csvNetwork
</pre>