Parameters¶

• Table of contents
• Parameters
  • Sort 0.2 / 0.3
    • Validation
  • Column 0.2 / 0.3
    • Validation
  • Limit 0.2 / 0.3
    • Validation
  • Search 0.3
    • Usage
      • Logical connections
      • Queries
      • Explained Example:
  • Filtering 0.2
    • Validation
  • Pagination (page / first / last) 0.2 / 0.3
    • Validation
  • Show/Hide Types 0.2 / 0.3
    • Validation
  • Format 0.2 / 0.3
    • Validation
  • Type ID 0.2 / 0.3
    • Validation
  • Count 0.2 / 0.3
    • Validation
  • Download 0.2 / 0.3
    • Validation
  • Lang (Language) 0.2 / 0.3
    • Validation
  • Geometry 0.2 / 0.3
    • Validation

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

Sort 0.2 / 0.3¶

<'asc', 'desc'>

?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 0.2 / 0.3¶

<'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 0.2 / 0.3¶

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

Search 0.3¶

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

Search parameter:

?search={}

Logical operators:
These are not mandatory. or is the standard value.

 and, or 

Compare operators:

equal, notEqual, greaterThan*, greaterThanEqual*, lesserThan*, lesserThanEqual*
(* works only in combination with beginFrom, beginTo, endFrom, endTo)

Filterable categories:

entityName, entityDescription, entityAliases, entityCidocClass, entitySystemClass, entityID, typeID, typeName, typeDescription, valueTypeID, valueTypeName, beginFrom, beginTo, endFrom, endTo

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. Dates are always strings and needs the YYYY-MM-DD format (0852-01-03). There can be multiple search parameters. E.g:

?search={"valueTypeID":[{"operator":"equal","values":[123456]}], "typeName":[{"operator":"notEqual","values":["Chain", "Bracelet"],"logicalOperator":"and"}], "endFrom":[{"operator":"greaterThanEqual","values":["0830-01-01"]}]}&search={"valueTypeName":[{"operator":"equal","values":["Gold"]}]}

Logical connections¶

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

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

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

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

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:

{"operator":"equal","values":[123456],"logicalOperator":"or"}
{"operator":"notEqual","values":["string", "otherString"],"logicalOperator":"and"}
{"operator":"greaterThanEqual","values":["0830-01-01"]}

Explained Example:¶

With the example above, we can textualize the outcome:

?search={"valueTypeID":[{"operator":"equal","values":[123456],"logicalOperator":"or"}, "typeName":[{"operator":"notEqual","values":["Chain", "Burial object"],"logicalOperator":"and"]}&search={"valueTypeName":[{"operator":"equal","values":["Gold"],"logicalOperator":"or"}]}

Get entities which has the valueTypeID 123456 AND NOT the types called "Chain" AND "Burial object", OR all entities which has the valueTypeName "Gold".

Filtering 0.2¶

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

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

?filter=<XXX>

Validation¶

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

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) 0.2 / 0.3¶

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 0.2 / 0.3¶

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

?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 0.2 / 0.3¶

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 0.2 / 0.3¶

<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 0.2 / 0.3¶

<>

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 0.2 / 0.3¶

<>

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) 0.2 / 0.3¶

<'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 0.2 / 0.3¶

   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