Community GeoJSON Format

Overview

This is a distributable set of data files for a HERE Venues Community with the geometric data given in GeoJSON format.

The specification for the GeoJSON format is at http://www.geojson.org

There are three different file types in the data set.

  • Community Map - This contains the Community, Drawing and Level information for the community. It does not include the geometry, which is given in a separate file. The structure of this file is similar to the structure of a GeoJSON.
     
  • Level Geometry - This file includes all the geometry for a given level. The file is in the format of a GeoJSON Feature Collection.
     
  • Community Entity - This file contains all the Entities in the Community. The structure of the file is similar to the structure of a GeoJSON.

Curves

The native HERE Venues map geometry includes bezier curves, similar to an SVG. These curves are flattened to give the standard GeoJSON geometry types. In addition the geometry files are available without flattening. This file includes a custom GeoJSON geometry type "Path" which is defined in this document.

Language

If a community has data in multiple languages, all languages are present in the data set.

  • In the community object the default language and the list of all the languages is given.
     
  • The "properties" entry for an object includes all properties that are either language independent or properties in the default language.
     
  • Additional property entries are added for each additional language. The label for these entries is "properties" + ":" + language code. These entries only include the properties specific to these languages.

Properties

In the properties description for each object type it lists the allowed properties. This includes an entry for HERE Venues standard object properties. These can be found in the Properties presets file. There are potentially also other properties in the GeoJSON file that are not standard properties on HERE Venues map objects. These additional GeoJSON properties are listed in this document.

Standard HERE Venues properties are typically string valued but they can also have values that are arrays of strings. The recommended format each property is listed in the presets document.

When a property does have multiple values in an array, the property in the GeoJSON will be given with a JSON array of strings. Otherwise a string value will be given.

Internal Addresses

Internal addresses will be displayed as a full internal address string. Each key value pair will be displayed as key + space + value. If the key is null, only the value is displayed. For both geometries and entities with multiple key value pairs the key value pairs will be separated by a comma + space, ", ". An example of this is "building 3, room 241".

Community Map

The Community map file contains the organizational structure for the community. It is composed of the Community Map JSON and any contained objects.

Name format: com-map_[community ID]_[data version].json

The data version comes from the snapshot during the release process. For data drawn directly from the active DB rather than released snapshot the version is given as 0.

Community Map JSON

{
     "id": community id,
     "obj_type": "CommunityMap",
     "map_version": map version,
     "entity_version": entity version,
     "properties": property map // see below
     "languages": languages array
     "default_lang": lang,
     "location": lat lon geojson point for community
     "drawings":[drawing list...] //see "Drawing JSON
}

Properties

Standard community properties, defined in the property keys from HERE Venues meta data.

Drawing JSON

{
     "id": drawing id,
     "obj_type": "Drawing",
     "levels": level list, // see "Level JSON"
     "properties": property map, // see below
     "object_groups": map type list, // see below
     "ref_frame":{
             "transform": transform from local to lat lon coordinates
             "height": height in local coordinates
             "width": width in local coordinates
             "angle_deg": default angle,
             "local2m": scale factor to convert local coords to meters
             }   
}

Properties

  • Standard drawing properties, defined in the property keys from HERE Venues meta data.
     
  • is_root (Optional, defaults to false) - This flag indicates if this is the root drawing in the community.
     
  • DEPRECATED: display_name - This is a derived display name for the drawing. The drawing may independently have a "name" property.
    • "display_name" will continue to appear in the drawing properties for the time being. However, it will be removed in the future. Use the property "name" instead.

Local Coordinates

Local coordinates are a set of coordinates defined locally to the venue. The coordinate system is also defined with a natural orientation, as opposed to north up. The local coordinates are used in the version of the files with the path json. The files with standard GeoJSON geometry types uses standard WGS84 coordinates.

Level JSON

{
     "id": level id,
     "obj_type": "Level",
     "properties": property map, //see below
}

Properties

  • Standard level properties, defined in the property keys from HERE Venues meta data.
  • zlevel - The zlevel, or ordering parameter, for the level
  • main (Optional, default to false) - This indicates if this drawing is the main level for this drawing.
  • root_geom - geometry id for the root geometry
  • parent_level - level id of the parent level

Level Geometry

The level geometry is held in a separate file. There are two versions, one with standard flattened geometry and one with JSON Path geometry.

Standard GeoJSON Name format:

geojson-level-geom_[community ID].[drawing ID].[level ID]_[data version].json

Path GeoJSON Name format:

path-level-geom_[community ID].[drawing ID].[level ID]_[data version].json

The data version comes from the snapshot during the release process. For data drawn directly from the active DB rather than released snapshot the version is given as 0.

LevelGeometry Feature Collection GeoJSON

{
     "id":level id,
     "drawing_id":drawing id,
     "community_id":community id,
     "map_version":map version,
     "entity_version":entity version,
     "obj_type":"LevelGeometry",
     "type":"FeatureCollection",
     "properties":property map, //same as Level object
     "crs":crs //see below
     "features":geometry list, //See "Geometry Feature GeoJSON"
}

CRS

An optional parameter for a GeoJSON is the CRS. If the CRS is not present the data will be given in WGS84 lat lon coordinates. If the CRS is null then the coordinates can not be assumed.

For the HERE Venues Maps data, the Data will be given either in WGS84 latitude and longitude coordinates for a standard GeoJSON or in local map coordinates as defined in the drawing object for a Path GeoJSON. If the latitude and longitude are used, the CRS is omitted. If local coordinates are used the CRS entry will be included with a value of null.

Geometry Feature GeoJSON

There are two formats available for the geometry geojson. Their is the standard GeoJSON which includes flattened geometry paths. Then there is the non-standard Path GeoJSON which displays the full curved path.

{
     "id": geometry id,
     "obj_type": "Geometry",
     "type": "Feature",
     "properties": property map, //see below
     "group": group id, //used to group geom across levels
     "is_group_main": is main geom, //see below
     "geometry": geometry GeoJSON or geometry path,
     "line_width": physical width, //For linear areas only. see below
     "label_area": label area, //see below
     "location": point geoJSON //for non-point geometry only
     "links": links json //see below
}

Properties

  • Standard geometry properties, defined in the property keys from HERE Venues meta data.
  • is_root (Optional, defaults to false) - is root geom for drawing
  • int_address (Optional, defaults to none) - internal address string, such as "room 213", if applicable.
  • entity_name - A name derived from any entities associated with the geometry, if applicable. The geometry may also have its own "name" property.
  • entities - The list of standard entities associated with this geometry, if applicable.
  • internal_entities - The list of internal entities associated with this geometry, if applicable.

A loose distinction between the entities list and the internal entities list is that the entity name for the geometry is derived from the objects in the entities list. The internal entities are contained in the geometry but are not used to construct the standard entity name for the object. An example where internal entities could be used is in a sectional mall map, where individual stores are not listed for each section. It is not a standard practice for HERE Venues to create sectional mall maps.

Root Geometry

A level may have a root geometry. This geometry is a child (normal) geometry in another drawing, the parent drawing.

There are three display scenarios for a root geometry:

  • normal display - In this case the geometry is displayed in the child drawing the same way it is displayed in the parent drawing. It will contain the same information in both the parent and child level geometry objects.
  • no display - In this case the root geometry is not displayed in the child. Here it will not be included in the child level geometry.
  • display as background - In this case the geometry object should be displayed as a special "background". Here the geometry is included in the child level geometry object, with a reduced set of properties.
    • type - given as the background type name.
    • is_root - set to true

Line Width

The basic geometry types are point, line and area. HERE Venues defines an additional type linear area. This is an area object that is defined as a line with an additional parameter width, corresponding to a physical width. This width is given in units of meters if the coordinates system is WGS84 and it is given in local coordinate units if the local coordinate system is used.

Geometry Group

A geometry group is used to group geometry that exists across multiple levels. The group has a main geometry, denoted by the "is_group_main" flag. The geometry id for the main geometry can often be used as a stand in to represent a single geometry id for a given group. The "is_group_main" flag is optional and defaults to false if it is not present.

Label Area

This is a rectangle constructed for rendering a label. Unless there is a property "external_label" on the geometry, the rectangle will be fully enclosed in the geometry. The value is given as a json array: [center X, center Y, width, height, angle].

  • The center X and Y are given in the same coordinate system as the geometry.
  • The width and height are given in meters for WGS84 and local coordinates if the local coordinate system is used.

Path GeoJSON

GeoJSON structure is defined by the standard.

GeoJson Path is defined as follows:

{
"type": "Path",
     "coordinates": [[integer command,x0,y0...],...]
     "area":true/false
}

The coordinates are given as an array of instructions. Each instruction includes a command integer, given in the table below, and a list of arguments that are dependant on the value if the command.

The commands are derived from the SVG Path commands. However, since JSON does not support characters and to make the path more compact, an integer is used to express the commands. The mapping of SVG command values to JSON command integers is given below.

For a reference on SVG commands, see the URL http://www.w3.org/TR/SVG/paths.html.

Note: The origin of the mapping of the SVG commands to JSON commands comes from legacy requirements, as is often the case. The fact that the relative commands have an index of 10 greater than the absolute commands is strictly an accident of the fact that there are currently 10 commands. When new SVG commands are added this particular relation will no longer hold.

SVG Cmd JSON Cmd Name Arg Cnt Support
M 0 Move to 2 Y
m 10 Move to, Relative 2  
L 1 Line To 2 Y
I 11 Line To, relative 2  
H 6 Horizontal Line To 1  
h 15 Horizontal Line To, relative 1  
V 6 Vertical Line To 1  
v 16 Vertical Line To, relative 1  
Q 2 Quadratic Curve To 4 Y
q 12 Quadratic Curve To, relative 4  
T 7 Smooth Quadratic Curve To 2  
t 17 Smooth Quadratic Curve To, relative 2  
C 3 Cubic Curve To 6 Y
c 13 Cubic Curve To, relative 6  
S 8 Smooth Cubic Curve To 4  
s 18 Smooth Cubic Curve To, relative 4  
A 9 Arc To 7  
a 19 Arc To, relative 7  
Z 4 Close Path 0 Y
z 14 Close Path 0  

Example paths:

SVG: <path d="M100,200 C100,100 250,100 250,200 L400,300 Z" />

JSON:[[0,100,200],[3,100,100,250,100,250,200],[1,400,300],[4]]

Community Entities

These are in a JSON.

Think about split between community entity entry and community map entry. Maybe we want to split them by property, some going to entity and map.

Name format:

com-entity_[community ID]_[data version].json

The data version comes from the snapshot during the release process. For data drawn directly from the active DB rather than released snapshot the version is given as 0.

Community Entities JSON

{
     "id":community id,
     "name":community name, //name only,in default lang
     "obj_type":"CommunityEntities",
     "map_version":map version,
     "entity_version":entity version,
     "entities":entity list, //see "Entity JSON"
}

Entity JSON

{
     "id":entity id,
     "obj_type":"Entity",
     "properties":property map, //see below
}

Properties

  • Standard entity properties, defined in the property keys from HERE Venues meta data.
  • chain (Optional, defaults to null) - chain id, // if applicable
  • int_address (Optional, defaults to null) - full address string. see internal address section in the overview
  • geometry (Optional, defaults to null) - Matched geometry, as an array of arrays. The internal array has the format:
    • [geometry ID,isIdentifier] - If "isIdentifier" is true the geometry is appears in the "entities" list for the geometry, if "isIdentifier" is false it appears in the "internal entities" list for the geometry.

Last Reviewed 11/21/2015
Download a copy by clicking this link.
Contact venues.support@here.com if you have any questions. 

FAQs
 
In the GeoJSON files, what are the units used for dimensionful quantities. 
 
The coordinates are in degrees (latitude, longitude). Distances are in meters. 
 
What native format do you use in house? Is it based on OSG WKT/WKB and an RDMS? Or do you use a known CAD format? The reason I ask is that 1) GeoJSON may result in large file if we keep lots of geometric detail and 2) for my work, I will be using a Spatialite DB (or at least SQLite).
 
We use a proprietary format internally. 
 
Will you be doing the georeferencing and setting up the CRS for the floorplans? How accurate is the georeferencing?
 
The CRS is WGS84 for the GeoJSONs. The absolute georeferencing error is 3 to 5 meters. The relative error is typically much smaller. 
 
Do the GeoJSON files include outdoor property information as well? 
 
Yes, if the map contains parcel and property information like parking lots, nearby roads, parking spaces, sidwalks and other details, the information is available in the GeoJSON files. 

When you create maps, do you capture any vertical information such as floor height, ceiling height, internal wall height or height of obstacles? 

We have a place to store the information in our maps, but as of December 2015, are not actively capturing this information. It is not part of our production process.