Trails

A resource that implements the concept of Trail defined in the AlpineBits® DestinationData Ontology.

A JSON object representing such a resource MUST contain the following fields:

  • type: the constant "trails" that identifies the resource as being of the type trail.

  • id: a string that uniquely and persistently identifies the trail within a SERVER. See the definition in basic-resource-schema.adoc#anchor-attributes.

  • attributes: an object containing the attributes of the trail.

  • relationships: an object containing the relationships of the trail to other resources.

  • links: an object containing the links related to the trail.

A trail resource is structured as follows:

{
  "type": "trails",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": { ... },
  "links": { ... }
}

1. Meta

See definition of the meta object in basic-resource-schema.adoc#anchor-metadata.

2. Attributes

The attributes object of a trail resource MUST contain the following fields:

  • abstract: a datatypes.adoc#anchor-text object containing a brief description for the trail. Nullable. See definition in basic-resource-schema.adoc#anchor-attributes.

  • address: an datatypes.adoc#anchor-address object representing the main address of the trail. The address should only be set if the trail is directly accessible from a public road. Nullable.

  • categories: an array of datatypes.adoc#anchor-type strings identifying the types instantiated by the trail. Nullable. The standard recommends the following trail types:, "alpinebits/ski-slope", "alpinebits/sledge-slope", "alpinebits/cross-country", "alpinebits/hiking", "alpinebits/mountain-bike", "alpinebits/climbing"

  • description: a datatypes.adoc#anchor-text object containing a description of the trail. Nullable. Conditional Assignment. See definition in basic-resource-schema.adoc#anchor-attributes.

  • difficulty: an object containing the difficulty level of a ski slope, as in { "eu": "novice", "us": "beginner" }.

    The "eu" field refers to the European classification of ski slopes. Its possible values are "novice", "beginner", "intermediate", and "expert". The "us" field refers to the North American classification of ski slopes. Its possible values are "beginner", "beginner-intermediate", "intermediate", "intermediate-advanced", and "expert".

    Every such object MUST contain both fields and at least one of them MUST NOT be null. The field itself, however, is nullable.

  • geometries: an array of datatypes.adoc#anchor-geometry objects each of which represents the location of the trail in terms of GPS coordinates. There should be at most one geometry object of each type (e.g. Point, LineString). Nullable.

  • howToArrive: a datatypes.adoc#anchor-text object containing instructions on how to arrive at the trail. Nullable.

  • length: a number representing the total length of the trail in meters. The computation of the length (in the case of branching paths, for instance) is determined by the data provider. Nullable.

  • maxAltitude: a number representing the highest elevation point of the trail in meters above sea level. Nullable.

  • minAltitude: a number representing the lowest elevation point of the trail in meters above sea level. Nullable.

  • name: a datatypes.adoc#anchor-text object containing the complete name of the trail. Non-nullable. See definition in basic-resource-schema.adoc#anchor-attributes.

  • openingHours: an array of datatypes.adoc#anchor-hoursspecification representing the hours in which the trail is open to the public. Nullable.

  • shortName: a datatypes.adoc#anchor-text object containing a short name of the trail. Nullable. See definition in basic-resource-schema.adoc#anchor-attributes.

  • snowCondition: a datatypes.adoc#anchor-snow object containing the latest reported condition of the snow in the trail.

  • url: a datatypes.adoc#anchor-url describing the trail, such as a website or a Wikipedia page. Nullable.

A summary of the attributes is presented in the table below:

Field Type Constraints

abstract

datatypes.adoc#anchor-text

Nullable

address

datatypes.adoc#anchor-address

Nullable

categories

Array of datatypes.adoc#anchor-type

Nullable, Non-empty

difficulty

object

Nullable

description

datatypes.adoc#anchor-text

Nullable, Conditional Assignment

geometries

Array of datatypes.adoc#anchor-geometry

Nullable, Non-empty

howToArrive

datatypes.adoc#anchor-text

Nullable

length

number

Nullable, Unit of Measure, Greater than Zero

maxAltitude

number

Nullable, Unit of Measure

minAltitude

number

Nullable, Unit of Measure

name

datatypes.adoc#anchor-text

Non-nullable, Conditional Assignment

openingHours

Array of datatypes.adoc#anchor-hoursspecification

Nullable, Non-empty

shortName

datatypes.adoc#anchor-text

Nullable

snowCondition

datatypes.adoc#anchor-snow

Nullable

url

datatypes.adoc#anchor-url

Nullable

3. Relationships

The relationships object of a trail resource MUST contain the following fields:

A summary of the relationships is presented in the table below:

Field Type Constraints

multimediaDescriptions

basic-resource-schema.adoc#anchor-referencetomany object to Media Objects

Nullable, Non-empty

connections

basic-resource-schema.adoc#anchor-referencetomany object to Mountain Areas, Trails, Lifts and Snowparks

Nullable, Non-empty

See definition of the links object in basic-resource-schema.adoc#anchor-links.

5. Endpoints

The following endpoints in this API specification return trail resources:

  • https://example.com /1.0/trails: returns a collection of trails.

  • https://example.com /1.0/trails/:id: returns the trail identified by the :id parameter.

  • https://example.com /1.0/trails/:id/connections: returns a collection of resources which may include trails.

  • https://example.com /1.0/lifts/:id/connections: returns a collection of resources which may includetrails.

  • https://example.com /1.0/mountainAreas/:id/trails: returns a collection of trails.

  • https://example.com /1.0/mountainAreas/:id/connections: returns a collection of resources which may include trails.

  • https://example.com /1.0/snowparks/:id/connections: returns a collection of resources which may include trails.

6. Examples

The following example contains the minimal information required for a trail resource:

{
  "type": "trails",
  "id": "1",
  "meta": {
    "dataProvider": null,
    "lastUpdate": null
  },
  "attributes": {
    "name": {
      "eng": "Falzeben I"
    },
    "shortName": null,
    "description": null,
    "abstract": null,
    "url": null,
    "categories": null,
    "length": null,
    "minAltitude": null,
    "maxAltitude": null,
    "difficulty": null,
    "address": {
      "street": null,
      "city": {
        "eng": "Merano"
      },
      "region": null,
      "country": "IT",
      "zipcode": null,
      "categories": null,
      "complement": null
    },
    "geometries": null,
    "howToArrive": null,
    "openingHours": null,
    "snowCondition": null
  },
  "relationships": {
    "connections": null,
    "multimediaDescriptions": null
  },
  "links": {
    "self": "http://example.com/1.0/trails/1"
  }
}

asciidoc/examples/trail.min.json

The following example illustrates the fields defined for trail resources:

{
  "type": "trails",
  "id": "1",
  "meta": {
    "dataProvider": "http://example.com",
    "lastUpdate": "2020-04-01T08:00:00+02:00"
  },
  "attributes": {
    "name": {
      "ita": "Falzeben I",
      "deu": "Falzeben I",
      "eng": "Falzeben I"
    },
    "shortName": {
      "eng": "Falzeben I"
    },
    "description": {
      "ita": "Falzeben I -  Discesa tra i boschi facile, immersa in un panorama da sogno ed ideale per bambini e principianti. Altezza/Lunghezza: 1900 altezza, 3500 m."
    },
    "abstract": {
      "ita": "Falzeben I -  Discesa tra i boschi facile, immersa in un panorama da sogno ed ideale per bambini e principianti."
    },
    "url": "http://example.com",
    "categories": [
      "alpinebits/ski-slope"
    ],
    "length": 2000,
    "minAltitude": 1500,
    "maxAltitude": 2500,
    "difficulty": {
      "eu": "novice",
      "us": "beginner"
    },
    "address": {
      "street": null,
      "city": {
        "eng": "Merano"
      },
      "region": null,
      "country": "IT",
      "zipcode": null,
      "categories": null,
      "complement": null
    },
    "howToArrive": {
      "ita": " Le fermate più vicine a Falzeben sono: Falzeben è a 41 metri di distanza a piedi e ci si arriva in 1 minuti di cammino; Villa Schäfer è a 808 metri di distanza a piedi e ci si arriva in 11 minuti di cammino."
    },
    "geometries": [
      {
        "type": "LineString",
        "coordinates": [
          [
            11.305682659149168,
            46.66705018437341
          ],
          [
            11.30692720413208,
            46.667182709603225
          ],
          [
            11.308064460754393,
            46.667491933875965
          ]
        ]
      }
    ],
    "openingHours": {
      "dailySchedules": {
        "2020-12-25": null
      },
      "weeklySchedules": [
        {
          "validFrom": "2020-01-01",
          "validTo": "2020-12-31",
          "monday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "tuesday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "wednesday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "thursday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "friday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "saturday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ],
          "sunday": [
            {
              "opens": "08:00:00+01:00",
              "closes": "18:00:00+01:00"
            }
          ]
        }
      ]
    },
    "snowCondition": {
      "primarySurface": "mtnxml/powder",
      "secondarySurface": "mtnxml/packed-powder",
      "baseSnow": 50,
      "baseSnowRange": {
        "lower": 40,
        "upper": 60
      },
      "latestStorm": 40,
      "obtainedIn": "2020-02-01",
      "snowOverNight": 5,
      "groomed": true,
      "snowMaking": false
    }
  },
  "relationships": {
    "connections": {
      "data": [
        {
          "type": "trails",
          "id": "2"
        },
        {
          "type": "trails",
          "id": "3"
        },
        {
          "type": "trails",
          "id": "4"
        },
        {
          "type": "lifts",
          "id": "1"
        }
      ],
      "links": {
        "related": "http://example.com/1.0/mountainAreas/1/connections/"
      }
    },
    "multimediaDescriptions": {
      "data": [
        {
          "type": "mediaObjects",
          "id": "2"
        }
      ],
      "links": {
        "related": "http://example.com/1.0/mountainAreas/1/multimediaDescriptions/"
      }
    }
  },
  "links": {
    "self": "http://example.com/1.0/trails/1"
  }
}

asciidoc/examples/trail.full.json