Project

General

Profile

Actions

The OpenAtlas API (Application programming interface) is implemented since version 5.0.0. Output is based on JSON-LD syntax and GeoJSON, therefore could be rendered in many web mapping applications.
In addition, Linked Places was used as standard. Further information can be found in the API Whitepaper.

Information about configuration: API Settings

Access

GeoJSON of an entity can be requested when entering this URL schema {domain}/api/{api version}/{entity_id} for example: openatlas.eu/api/0.1/entity/1234
Alternatively if advanced layout is selected in your profile a link to the GeoJSON of entities is shown on their info page.
If in the site settings the API option Public is activated (default is off) the API can be used even when not logged in.
The API is in active development, more formats and options will follow. The current version is 0.1, major changes may render former versions obsolete.

GeoJSON Structure

For the Version 0.1 OpenAtlas only supports GeoJSON. The structure for each entity is as followed. If a key:value pair is empty, it will not be shown in the output. For full examples of the GeoJSON templates please confer JSON Templates.

@context (required)

Contains the mappings for linked ontologies. We use the Linked Places mappings found in http://linkedpasts.org/assets/linkedplaces-context-v1.jsonld

e.g. "@context": "https://raw.githubusercontent.com/LinkedPasts/linked-places/master/linkedplaces-context-v1.jsonld"

type (required)

The type of each output is "FeatureCollection", according to GeoJSON-LD , containing one or more Feature objects.

feature[] (required)

Feature is a list, which can hold one or many feature objects. Each object can contain following elements:

@id (required)

This is a unique and permanent URI pointing to the entity in the OpenAtlas instance.

"@id": "http://thanados.openatlas.eu/entity/50505" 

crmClass (required)

Show CIDOC CRM class code and name based on the Erlangen CRM

"crmClass": "crm:E18_Physical_Thing" 

type (required)

The value for type is "feature" to state, that the object is a feature.

properties{} (required)

The property element holds one key:value pair, because of the GeoJSON requirement. The key is title, which is the preferred name label of the entity. In the OA form it is called Form field name.

         "properties":{
            "title":"Gars Thunau Obere Holzwiese" 
         }

when{}

When is the temporally scope of the represented feature. OpenAtlas only supports dates in the YYYY-MM-DD format, so no periods or extensions for approximate and uncertain (for more details: Date).
Each "when" contains one timespans[] . A timespan can contain start{} and/or end{}. start{} or end{} hold timestamp values and the comments for the dates.

         "when":{
            "timespans":[
               {
                  "end":{
                     "earliest":"0950-01-01",
                     "latest":"0950-12-31" 
                  },
                  "start":{
                     "earliest":"0750-01-01",
                     "latest":"0750-12-31" 
                  }
               }
            ]
         }

names[]

names is a list of Aliases.

         "names":[
            {
               "alias":"Thunau Obere Holzwiese" 
            }
         ]

types[]

Represents a list of one or more types objects (nodes) for this feature. Identifier refers to the type entity of the type and label is the given name of the type. Hierarchy lists the super types in a string for the THANATOS front end. If the type is a value type, the unit and value is also shown.

         "types":[
            {
               "hierarchy":"Evidence > Archaeology",
               "identifier":"http://thanados.openatlas.eu/api/0.1/entity/5099",
               "label":"Excavation" 
            },
            {
               "hierarchy":"Dimensions",
               "identifier":"http://thanados.openatlas.eu/api/0.1/entity/26189",
               "label":"Length",
               "unit":"cm",
               "value":"200" 
            }
         ]

geometry{} (required)

A GeoJSON FeatureCollection must have one or more geometry elements to be valid. Therefore each entity, even if it has no geometric references has this entry:

         "geometry":{
            "geometries":[ ],
            "type":"GeometryCollection" 
         }

Type refers to geometric types according to RFC 7946 - The GeoJSON Format.

Geometries[] is a list of none or more geometric objects. Each of these objects have the following keys:

  • Type - Refers to the geometric types. OpenAtlas supports Point, Polygon and LineString
  • Title - The given name of this geometric object
  • Description - The given description of this geometric object
  • Coordinates[] - Is a list of none or more lists with positions of the object
             "geometry":{
                "geometries":[
                   {
                      "coordinates":[
                         21.53314304247,
                         41.528480700127
                      ],
                      "title":"Ōrěhovь Dolь",
                      "type":"Point" 
                   },
                   {
                      "coordinates":[
                         [
                            [
                               21.519985198975,
                               41.510119875951
                            ],
                            [
                               21.547966003418,
                               41.509991329146
                            ],
                            [
                               21.560153961182,
                               41.527471351458
                            ],
                            [
                               21.546764373779,
                               41.546745312346
                            ],
                            [
                               21.519470214844,
                               41.546231414598
                            ],
                            [
                               21.506080627441,
                               41.528113909357
                            ],
                            [
                               21.519985198975,
                               41.510119875951
                            ]
                         ]
                      ],
                      "description":"A model of the village's boundaries.",
                      "title":"Ōrěhovь Dolь",
                      "type":"Polygon" 
                   }
                ],
                "type":"GeometryCollection" 
             }
    

links[]

These are the links to other gazetteers. At the moment OpenAtlas support GeoNames, as described in Place.

         "links":[
            {
               "identifier":"http://www.geonames.org/2763660",
               "type":"closeMatch" 
            }
         ]

relations[]

Is a list of one or more entities, which are linked through the CRM to this feature. Label represents the name of the entity, relationTo contains the direct link to this entity and relationType shows the property code from the model with which the entities are linked.

"relations":[
            {
               "label":"Cenotaph_A",
               "relationTo":"http://oa-dev.koschigel.de/api/0.1/entity/57167",
               "relationType":"crm:P46_is_composed_of" 
            },
            {
               "label":"Excavation",
               "relationTo":"http://oa-dev.koschigel.de/api/0.1/entity/5099",
               "relationType":"crm:P2_has_type" 
            }
]

descriptions[]

Contains the description of the entity.

         "description":[
            {
               "value":"In the area of Obere Holzwiese 215 inhumation burials were documented in different excavations[..]" 
            }
         ]

depictions[]

Is a list of all linked depictions or files. @id links directly to the file, title represents the given name and license contains the given license of the file.

         "depictions":[
            {
               "@id":"http://oa-dev.koschigel.de/api/0.1/entity/117992",
               "license":"CC BY-SA 4.0",
               "title":"oberleiserberg_map" 
            }
         ]

Updated by Alexander Watzinger 6 days ago · 117 revisions

Also available in: PDF HTML TXT