mapping-docs/reference/itinerary/GeoJSON and Vector Tiles/README.md at master · AlpacaTravel/mapping-docs

//:

"Redirect: https://github.com/AlpacaTravel/mapping-docs/blob/master/reference/itinerary/GeoJSON%20and%20Vector%20Tiles/README.md"

name: Alpaca Itinerary v1 GeoJSON/Tiles Reference generated: Tue Aug 30 2022

Overview

Alpaca Itinerary v1 Tileset and GeoJSON formats include geometries for plotted itineraries for locations, directions and route segments. These provide access for you to create your representation of the itinerary within your mapping platform or application.

Attribution

When you publicly display maps that use Alpaca Itinerary vector tiles or geojson data, you must display proper attribution.

IDs

Each feature contains feature.id, which assists you in interacting with features using products such as Mapbox. Also often included is feature.properties.id which supplies you with Alpaca identifiers in order to further select additional data about that feature from our API.

In some cases, we provide feature.properties.external_ref and feature.properties.external_source in order for authors to attach other external platform identifiers to assist connecting data with data that may appear in another platform of choice.

Data Stability

Similarly to other vector tile products (such as Mapbox Streets v8 ❤️), we are following similar goals behind the Alpaca Itinerary v1 data set to preserve compatability with styling or other uses of data properties.

Here are our goals;

Layers
- Preserve existing layers
- Add new layers that could contain additional features from itineraries
Fields
- Preserve existing fields
- Add new fields where additional use cases or feature data is advantageous to be included
Field values
- The meaning of existing values will not change
- Values of specific features may change to correct errors or other real-world updates (such as changes in underlying data provided to us)
- New values may be added
- null values will be noted, and fields that are optional will be marked so. null or optional values should not replace existing fields that have not allowed it prior

Common Attributes

The specification includes a number of feature attributes that can be common to more than one feature type.

Hierarchy

Attributes provide a means of querying hierarchical relationships as well as ordering between sibling elements

Value	Description
`lft` number Example: `5`	Left outermost value
`rgt` number Example: `6`	Right outermost value
`depth` number Example: `0`	The depth of the element, relative to ancestors

Location Numbering

Attributes to assist presenting position numbers assigned to locations

Value	Description
`list_pref` string optional Example: `"unordered"`	Any associated list presentation preference applied to this location
`location_num` number optional Example: `2`	The location number, relative to the sibling locations
`location_num_dfs` number optional Example: `9`	The accumulative location number for the overall itinerary

Node Reference

Attributes to assist reference more information from the Alpaca GQL

Value	Description
`id` string Example: `"itinerary/XXX/location/XXX"`	The Alpaca related node identifier

Target Node Reference

Attributes to assist targeting another node

Value	Description
`target` string Example: `"itinerary/XXX/location/XXX"`	The Alpaca related node identifier

External Identifiers

Attributes to identify this feature in a developers external platform

Value	Description
`external_ref` string optional Example: `"myplatform-UUID"`	Reference identifier in external platform, if any
`external_source` string optional Example: `"myplatform-section-UUID"`	Reference source in external platform, if any

Itinerary Segments

Reference assignments to itinerary segment identifiers

Value	Description
`segments` text[] Example: `["UUID"]`	A collection of assigned segment identifiers for this feature, if any

Itinerary Directions Segment Properties

Reference assignments to itinerary segment identifiers

Value	Description
`loc_segments_int` text[] Example: `["UUID"]`	Intersection of segments between the origin and destination locations

Icon

Attributes that describe the associated itinerary icon

Value	Description
`icon` text optional Example: `"itinerary/XXX/icon/YYY"`	The id of the itinerary icon

Content

Attributes that contain content supplied by the user

Value	Description
`label` text optional Example: `"Mavis the Grocer"`	The primary label associated with this feature
`tags` text[] optional Example: `["a tag","another tag"]`	Any assigned user tags

Viewport Adjustments for a center position

Attributes that describe any adjustments for the camera

Value	Description
`bearing` number optional Example: `270`	Bearing, from 0-360
`pitch` number optional Example: `60`	Pitch, from 0-60
`zoom` number optional Example: `17`	Zoom, from 0-20+

Viewport Adjustments for Bounds

Attributes that describe any adjustments for the camera

Value	Description
`bearing` number optional Example: `270`	Bearing, from 0-360
`pitch` number optional Example: `60`	Pitch, from 0-60

Feature Flags Behaviour

Attributes that can help describe interactions with this feature, such as omitting it from a list, map or providing further detail

Value	Description
`flags` text optional Example: `["omit-list"]`	A collection of keys relating to which behaviours should be omitted when interacting with this feature

Camera Type

Determines the camera type

Value	Description
`type` text Example: `"geometry-bounds"`	Determines the camera type for a series of camera configurations availabe

Collection Position

Attributes that assist contextualise the ordering of this feature with other collection results

Value	Description
`index` number Example: `3`	The index of this element within the collection (0 indexed)
`length` number Example: `4`	The total length of the collection this feature is part of

Progress

Attributes to describe progress along a feature, such as breaking up a path line string into various percentage of length

Value	Description
`percentage` number Example: `50`	Percentage progress along this feature (Values: 0, 25, 50, 75, 100)

Distance

Attributes to assist presenting the distance of the linestring feature

Value	Description
`distance` number Example: `400`	Distance in meters

Duration

Attributes relating to the expected duration to travel this feature

Value	Description
`duration_min` number optional Example: `40`	Minimum duration (in minutes)
`duration_max` number optional Example: `40`	Maximum duration (in minutes)

Travel Mode

Attributes to describe the mode of transportation used in this feature

Value	Description
`mode` enum Example: `"car"`	A series of values to describe the mode of transport (e.g. foot, car) for this feature

Multi-modal Travel Properties

Describes when multiple modes of transport are used in Itinerary Directions

Value	Description
`multi_modal` boolean optional Example: `true`	Whether multiple modes of transport are used to describe the itinerary directions

RouteSegment Travel Mode

Attributes to describe the aggregated route segment travel modes

Value	Description
`route_segment_modes` enum[] Example: `["car","foot"]`	A collection of values to describe all modes of transport used within the associated RouteSegment features

RouteSegment / ItineraryDirections Relationship

Attributes to describe the relationship of route segments to their directions counterpart

Value	Description
`directions` string Example: `"itinerary/XXX/directions/XXX"`	The node reference ID of the associated Itinerary Directions feature

ItineraryDirections / RouteSegment Relationship

Attributes to describe the relationship of directions to the route segments counterpart

Value	Description
`route_segment` string Example: `"itinerary/XXX/directions/XXX/segment/unstable.0"`	The node reference ID of the associated Route Segment feature

Origin / Destination Node Reference

Attributes to create relationships to Locations

Value	Description
`origin` string optional Example: `"itinerary/XXX/location/XXX"`	The origin Itinerary Location Node Reference
`dest` string optional Example: `"itinerary/XXX/location/XXX"`	The destination Itinerary Location Node Reference

Optional Stop information

Attributes to assist presenting optional locations

Value	Description
`optional` boolean optional Example: `true`	Whether this feature has been indicated as an optional stop on the itinerary

GeoJSON Reference

Features are container within the GeoJSON FeatureCollection features array. The bbox property often included provide a bounding box calculation for the features.

{
  type: 'FeatureCollection',
  features: [...],
  bbox: [1, 1, 2, 3]
}

Each feature of the itinerary has a number of GeoJSON Feature objects. The object contains a number of properties, including an id, geometry, properties and often the bbox property.

The geometry property provides an encoding of geometry depending on the geometry type, such as point, linestring, multilinestring or polygon. An example of of a geometry would be { type: 'point', coordinates: [1, 1] }).

The properties property provides a number of attributes about the feature corresponding to the type of feature (differentiated by the class attribute).

{
  id: 123,
  type: 'Feature',
  geometry: { ... },
  properties: { ... },
  bbox: [1, 1, 2, 2]
}

Tileset Reference

Opposed to serving the full GeoJSON features to your users, you can leverage the vector tilesets to load in details at specific map areas and zoom levels to optimise map loading.

Features are organised into several layers within the vector tilesets offered. You can selectively target features within a specific layer

The Alpaca Itinerary v1 contains the following layers in the tileset.

Layer	Minimum zoom level	Feature Classes
default Default layer containing itinerary features	0	`location_marker`, `location_directions_preference`, `directions_distance_progress`, `directions_path`, `directions_path_waypoint`, `directions_path_distance_progress`
metadata Contains miscellaneous features to assist presentation of features (stripped from vector tiles)	0	`camera`

Features

The Alpaca Itinerary v1 features include a number of representations of the ItineraryLocation, ItineraryDirections and RouteSegment types.

Type	Description
location_marker	The primary marker for this location
location_directions_preference	The position preference to obtain directions to
directions_distance_progress	Point representing a percentiles of progress along the overall directions
directions_path	Itinerary Directions path for itinerary directions
directions_path_waypoint	The waypoints used for directing along the Itinerary Directions Path
directions_path_distance_progress	Point representing a percentiles of progress along the route segment
camera	Geometry to assist presenting cameras with associated target features

Feature `location_marker`

Tile Layer: default Geometry: Point

The primary marker for this location

Property	Description
`class` string	`location_marker`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`external_ref` string optional	External Identifiers `external_ref` Reference identifier in external platform, if any
`external_source` string optional	External Identifiers `external_source` Reference source in external platform, if any
`segments` text[]	Itinerary Segments `segments` A collection of assigned segment identifiers for this feature, if any
`icon` text optional	Icon `icon` The id of the itinerary icon
`label` text optional	Content `label` The primary label associated with this feature
`tags` text[] optional	Content `tags` Any assigned user tags
`flags` text optional	Feature Flags Behaviour `flags` A collection of keys relating to which behaviours should be omitted when interacting with this feature
`optional` boolean optional	Optional Stop information `optional` Whether this feature has been indicated as an optional stop on the itinerary
`list_pref` string optional	Location Numbering `list_pref` Any associated list presentation preference applied to this location
`location_num` number optional	Location Numbering `location_num` The location number, relative to the sibling locations
`location_num_dfs` number optional	Location Numbering `location_num_dfs` The accumulative location number for the overall itinerary

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "location_marker",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "external_ref": "myplatform-UUID",
    "external_source": "myplatform-section-UUID",
    "segments": ["UUID"],
    "icon": "itinerary/XXX/icon/YYY",
    "label": "Mavis the Grocer",
    "tags": ["a tag", "another tag"],
    "flags": ["omit-list"],
    "optional": true,
    "list_pref": "unordered",
    "location_num": 2,
    "location_num_dfs": 9
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}

Feature `location_directions_preference`

Tile Layer: default Geometry: Point

The position preference to obtain directions to

Property	Description
`class` string	`location_directions_preference`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`external_ref` string optional	External Identifiers `external_ref` Reference identifier in external platform, if any
`external_source` string optional	External Identifiers `external_source` Reference source in external platform, if any
`segments` text[]	Itinerary Segments `segments` A collection of assigned segment identifiers for this feature, if any
`optional` boolean optional	Optional Stop information `optional` Whether this feature has been indicated as an optional stop on the itinerary
`flags` text optional	Feature Flags Behaviour `flags` A collection of keys relating to which behaviours should be omitted when interacting with this feature
`list_pref` string optional	Location Numbering `list_pref` Any associated list presentation preference applied to this location
`location_num` number optional	Location Numbering `location_num` The location number, relative to the sibling locations
`location_num_dfs` number optional	Location Numbering `location_num_dfs` The accumulative location number for the overall itinerary

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "location_directions_preference",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "external_ref": "myplatform-UUID",
    "external_source": "myplatform-section-UUID",
    "segments": ["UUID"],
    "optional": true,
    "flags": ["omit-list"],
    "list_pref": "unordered",
    "location_num": 2,
    "location_num_dfs": 9
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}

Feature `directions_distance_progress`

Tile Layer: default Geometry: Point

Point representing a percentiles of progress along the overall directions

Property	Description
`class` string	`directions_distance_progress`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`percentage` number	Progress `percentage` Percentage progress along this feature (Values: 0, 25, 50, 75, 100)
`multi_modal` boolean optional	Multi-modal Travel Properties `multi_modal` Whether multiple modes of transport are used to describe the itinerary directions
`origin` string optional	Origin / Destination Node Reference `origin` The origin Itinerary Location Node Reference
`dest` string optional	Origin / Destination Node Reference `dest` The destination Itinerary Location Node Reference
`mode` enum	Travel Mode `mode` A series of values to describe the mode of transport (e.g. foot, car) for this feature
`route_segment` string	ItineraryDirections / RouteSegment Relationship `route_segment` The node reference ID of the associated Route Segment feature

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "directions_distance_progress",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "percentage": 50,
    "multi_modal": true,
    "origin": "itinerary/XXX/location/XXX",
    "dest": "itinerary/XXX/location/XXX",
    "mode": "car",
    "route_segment": "itinerary/XXX/directions/XXX/segment/unstable.0"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}

Feature `directions_path`

Tile Layer: default Geometry: LineString, MultiLineString

Itinerary Directions path for itinerary directions

Property	Description
`class` string	`directions_path`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`distance` number	Distance `distance` Distance in meters
`duration_min` number optional	Duration `duration_min` Minimum duration (in minutes)
`duration_max` number optional	Duration `duration_max` Maximum duration (in minutes)
`multi_modal` boolean optional	Multi-modal Travel Properties `multi_modal` Whether multiple modes of transport are used to describe the itinerary directions
`mode` enum	Travel Mode `mode` A series of values to describe the mode of transport (e.g. foot, car) for this feature
`origin` string optional	Origin / Destination Node Reference `origin` The origin Itinerary Location Node Reference
`dest` string optional	Origin / Destination Node Reference `dest` The destination Itinerary Location Node Reference
`route_segment` string	ItineraryDirections / RouteSegment Relationship `route_segment` The node reference ID of the associated Route Segment feature
`index` number	Collection Position `index` The index of this element within the collection (0 indexed)
`length` number	Collection Position `length` The total length of the collection this feature is part of
`loc_segments_int` text[]	Itinerary Directions Segment Properties `loc_segments_int` Intersection of segments between the origin and destination locations

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "directions_path",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "distance": 400,
    "duration_min": 40,
    "duration_max": 40,
    "multi_modal": true,
    "mode": "car",
    "origin": "itinerary/XXX/location/XXX",
    "dest": "itinerary/XXX/location/XXX",
    "route_segment": "itinerary/XXX/directions/XXX/segment/unstable.0",
    "index": 3,
    "length": 4,
    "loc_segments_int": ["UUID"]
  },
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [0, 0],
      [5, 5],
      [10, 10]
    ]
  },
  "bbox": [0, 0, 10, 10]
}

Feature `directions_path_waypoint`

Tile Layer: default Geometry: Point

The waypoints used for directing along the Itinerary Directions Path

Property	Description
`class` string	`directions_path_waypoint`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`origin` string optional	Origin / Destination Node Reference `origin` The origin Itinerary Location Node Reference
`dest` string optional	Origin / Destination Node Reference `dest` The destination Itinerary Location Node Reference
`index` number	Collection Position `index` The index of this element within the collection (0 indexed)
`length` number	Collection Position `length` The total length of the collection this feature is part of
`multi_modal` boolean optional	Multi-modal Travel Properties `multi_modal` Whether multiple modes of transport are used to describe the itinerary directions
`mode` enum	Travel Mode `mode` A series of values to describe the mode of transport (e.g. foot, car) for this feature
`route_segment` string	ItineraryDirections / RouteSegment Relationship `route_segment` The node reference ID of the associated Route Segment feature
`loc_segments_int` text[]	Itinerary Directions Segment Properties `loc_segments_int` Intersection of segments between the origin and destination locations

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "directions_path_waypoint",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "origin": "itinerary/XXX/location/XXX",
    "dest": "itinerary/XXX/location/XXX",
    "index": 3,
    "length": 4,
    "multi_modal": true,
    "mode": "car",
    "route_segment": "itinerary/XXX/directions/XXX/segment/unstable.0",
    "loc_segments_int": ["UUID"]
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}

Feature `directions_path_distance_progress`

Tile Layer: default Geometry: Point

Point representing a percentiles of progress along the route segment

Property	Description
`class` string	`directions_path_distance_progress`
`lft` number	Hierarchy `lft` Left outermost value
`rgt` number	Hierarchy `rgt` Right outermost value
`depth` number	Hierarchy `depth` The depth of the element, relative to ancestors
`id` string	Node Reference `id` The Alpaca related node identifier
`percentage` number	Progress `percentage` Percentage progress along this feature (Values: 0, 25, 50, 75, 100)
`origin` string optional	Origin / Destination Node Reference `origin` The origin Itinerary Location Node Reference
`dest` string optional	Origin / Destination Node Reference `dest` The destination Itinerary Location Node Reference
`multi_modal` boolean optional	Multi-modal Travel Properties `multi_modal` Whether multiple modes of transport are used to describe the itinerary directions
`index` number	Collection Position `index` The index of this element within the collection (0 indexed)
`length` number	Collection Position `length` The total length of the collection this feature is part of
`mode` enum	Travel Mode `mode` A series of values to describe the mode of transport (e.g. foot, car) for this feature
`route_segment` string	ItineraryDirections / RouteSegment Relationship `route_segment` The node reference ID of the associated Route Segment feature
`loc_segments_int` text[]	Itinerary Directions Segment Properties `loc_segments_int` Intersection of segments between the origin and destination locations

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "directions_path_distance_progress",
    "lft": 5,
    "rgt": 6,
    "depth": 0,
    "id": "itinerary/XXX/location/XXX",
    "percentage": 50,
    "origin": "itinerary/XXX/location/XXX",
    "dest": "itinerary/XXX/location/XXX",
    "multi_modal": true,
    "index": 3,
    "length": 4,
    "mode": "car",
    "route_segment": "itinerary/XXX/directions/XXX/segment/unstable.0",
    "loc_segments_int": ["UUID"]
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}

Feature `camera`

Tile Layer: metadata Geometry: Polygon

Geometry to assist presenting cameras with associated target features

Property	Description
`class` string	`camera`
`target` string	Target Node Reference `target` The Alpaca related node identifier
`bearing` number optional	Viewport Adjustments for Bounds `bearing` Bearing, from 0-360
`pitch` number optional	Viewport Adjustments for Bounds `pitch` Pitch, from 0-60

Example

{
  "type": "Feature",
  "id": 123,
  "properties": {
    "class": "camera",
    "target": "itinerary/XXX/location/XXX",
    "bearing": 270,
    "pitch": 60,
    "type": "geometry-bounds"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [0, 0],
        [5, 0],
        [5, 5],
        [0, 5],
        [0, 0]
      ]
    ]
  },
  "bbox": [0, 0, 10, 10]
}

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Overview

Attribution

IDs

Data Stability

Common Attributes

Hierarchy

Location Numbering

Node Reference

Target Node Reference

External Identifiers

Itinerary Segments

Itinerary Directions Segment Properties

Icon

Content

Viewport Adjustments for a center position

Viewport Adjustments for Bounds

Feature Flags Behaviour

Camera Type

Collection Position

Progress

Distance

Duration

Travel Mode

Multi-modal Travel Properties

RouteSegment Travel Mode

RouteSegment / ItineraryDirections Relationship

ItineraryDirections / RouteSegment Relationship

Origin / Destination Node Reference

Optional Stop information

GeoJSON Reference

Tileset Reference

Features

Feature location_marker

Example

Feature location_directions_preference

Example

Feature directions_distance_progress

Example

Feature directions_path

Example

Feature directions_path_waypoint

Example

Feature directions_path_distance_progress

Example

Feature camera

Example

Feature `location_marker`

Feature `location_directions_preference`

Feature `directions_distance_progress`

Feature `directions_path`

Feature `directions_path_waypoint`

Feature `directions_path_distance_progress`

Feature `camera`