Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Geofencing V8 API
description: Geofence asset positions against HERE Map objects or custom fence objects
termsOfService: https://developer.here.com/terms-conditions
license:
name: HERE Documentation License
url: https://legal.here.com/en-gb/terms/documentation-license
version: 8.3.3
servers:
- url: https://geofencing.hereapi.com
description: Generated server url
security:
- apiKey: []
- bearerTokenAuth: []
tags:
- name: Geofencing V8
description: The HERE Geofencing API can geofence asset positions against HERE Map objects or custom fence objects
paths:
/v8/geofence:
get:
tags:
- Geofencing V8
summary: Simple and fast search for geometries on HERE Map Content layers, extensible…
description: 'Simple and fast search for geometries on HERE Map Content layers, extensible with custom geometry layers
Note: We recommend using POST requests for large payloads, as GET requests may be constrained by request-line length limits imposed by load balancers.'
operationId: Geofencing API geofence
parameters:
- name: layers
in: query
description: "Comma-separated list of layers to search, with layer names being case-insensitive.\n * Both custom layers and Map Attribute core map layers are supported.\n * Map Attribute layers categorized by functional class, like ROAD_GEOM_FC1 to FC5, can be selected by using `FCN` notation, e.g. `ROAD_GEOM_FCN`.\n * The maximum length of a layer name and the permitted characters can be looked up in the service via `/v8/maps/serviceconfiguration`.\n * Using the `attributes` parameter specific column attributes from a layer can be returned."
required: true
schema:
type: string
- name: in
in: query
description: 'Spatial filtering for multi layer search. For GET requests supported filter type is `point` with radius.
* Example: `in=point:41.93,12.43;r=40`
* Multipoint search is supported only via POST request with filter type `assetPositions`'
required: true
schema:
type: string
- name: filter
in: query
description: 'A SQL expression which is evaluated for each geometry returned from the specified layer list.
* Columns values for each geometry are available as predefined variables.
* When an expression is specified, only geometries where the expression evaluates to true are returned.
* Supported SQL filter operators include: `=`, `!=`, `>`, `<`, `AND`, `OR` and `LIKE`.
* Example: `filter=RATING > 3 AND NAME != ''MyPlace23'' AND NAME LIKE ''FOOD%''`.
* Parameter value must be url encoded when using special characters.
* This filter applies to all geometries and may be slow for large layers. To avoid service overload, filter expressions should not exceed 100 characters.
* The filter is applied across all objects from specified layers, so it is most effective when a single layer is requested.'
required: false
schema:
type: string
default: ''
- name: meta
in: query
description: When set to `1`, then meta info is returned in the response.
required: false
schema:
type: string
default: '1'
- name: attributes
in: query
description: 'A Semicolon-separated list of column names (in uppercase) to indicate which attributes will be included in the results.
* If the request specifies several layers, then pass attributes for each layer as a comma separated list.
* Default includes all columns from each layer.
* Example if `&layers=LINK_ATTRIBUTE2_FCn,LINK_ATTRIBUTE_FCn,ROAD_GEOM_FCn` are requested, then the columns can be restricted to only following `&attributes=PARKING_LOT_ROAD;CARPOOL_ROAD,PAVED;PRIVATE,BRIDGE;TUNNEL`.* `PARKING_LOT_ROAD` and `CARPOOL_ROAD` are from layer `LINK_ATTRIBUTE2_FCn`, `PAVED` and `PRIVATE` from `LINK_ATTRIBUTE_FCn`, `BRIDGE` and `TUNNEL` from `ROAD_GEOM_FCn` layer.'
required: false
schema:
type: string
- name: mapName
in: query
description: 'Optional. Map in which the specific layer or layers exist, which will be accessed to retrieve the layer content. If parameter is not specified, the behavior is: search in the default map where all custom layers are stored, which were created without `mapName` in `upload/modify` request.'
required: false
schema:
type: string
- name: assetId
in: query
description: "Optional. Identifier for the asset. If provided, the response will contain the assetId.\n * The maximum length of an asset id and the permitted characters can be looked up in the service via `/v8/maps/serviceconfiguration`."
required: false
schema:
type: string
- name: ownerAppId
in: query
description: Owner app_id that was used to upload a layer. It is mandatory when a granted app_id is used to access the layer.
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/MapAttributesV8Response'
post:
tags:
- Geofencing V8
summary: Simple and fast search for geometries on HERE Map Content layers, extensible…
description: Simple and fast search for geometries on HERE Map Content layers, extensible with custom geometry layers
operationId: Geofencing API geofencePost
parameters:
- name: in
in: query
description: 'Spatial filtering for multi layer search. For POST requests supported filter type is `assetPositions`.
* The POST body must contain a json structure, as specified in example below and explained in requestBody.
* Each asset `point` should have properties `lat`, `lon`, `layer` and `searchRadius`.
* The property `attributes` is optional. Specify a String array of column names (in uppercase) to specify which attributes from specific layer shall appear in the result. If omitted, the returned result will include all the attributes of the specified layer.
* Example POST body: {"point": [{ "lat" : 41.9101, "lon" : 12.5021, "layer" : "ROAD_GEOM_FC3", "searchRadius" : 100 },{ "lat" : 42.0299, "lon" : 12.6932, "layer" : "ROAD_GEOM_FC5", "searchRadius" : 200, "attributes" : ["LINK_ID", "NAME", "TUNNEL", "BRIDGE" ] }]}'
required: true
schema:
type: string
- name: filter
in: query
description: 'A SQL expression which is evaluated for each geometry returned from the specified layer list.
* Columns values for each geometry are available as predefined variables.
* When an expression is specified, only geometries where the expression evaluates to true are returned.
* Supported SQL filter operators include: `=`, `!=`, `>`, `<`, `AND`, `OR` and `LIKE`.
* Example: `filter=RATING > 3 AND NAME != ''MyPlace23'' AND NAME LIKE ''FOOD%''`.
* Parameter value must be url encoded when using special characters.
* This filter applies to all geometries and may be slow for large layers. To avoid service overload, filter expressions should not exceed 100 characters.
* The filter is applied across all objects from specified layers, so it is most effective when a single layer is requested.'
required: false
schema:
type: string
default: ''
- name: meta
in: query
description: When set to `1`, then meta info is returned in the response.
required: false
schema:
type: string
default: '1'
- name: mapName
in: query
description: 'Optional. Map in which the specific layer or layers exist, which will be accessed to retrieve the layer content. Default behavior: Check in the default map.'
required: false
schema:
type: string
- name: ownerAppId
in: query
description: Owner app_id that was used to upload a layer. It is mandatory when a granted app_id is used to access the layer.
required: false
schema:
type: string
requestBody:
description: Asset positions to geofence, sent as an application/json request body instead of query parameters. Each point has lat, lon, layer and searchRadius; the optional attributes array restricts the returned columns. Authentication `apiKey` must - and basic configuration parameters can remain in the query string.
content:
application/json:
schema:
$ref: '#/components/schemas/AssetPositions'
examples:
assetPositions:
description: assetPositions
value:
point:
- lat: 50.0996
lon: 8.67125
layer: MYTESTLAYER2
searchRadius: 15000
required: true
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/MapAttributesV8Response'
'415':
description: 'Bad mediatype. Supported values: application/json, text/plain'
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/MapAttributesV8Response'
/v8/geofence/upload:
post:
tags:
- Geofencing V8
summary: Import Geometries in a WKT or Shape File
description: Import polygons, polylines or points in WKT (Wellknown Text) or Shapefile format geometries using an HTTP POST request. A layer can contain only one geometry type - polygons, polylines or points, but not a mix of different types. After the response there is a delay of several seconds to compile, store and make the geometries available in the service.
operationId: Geofencing API v8UploadPost
parameters:
- name: layerId
in: query
description: 'Unique identifier for the layer in the format: {app_id}.{mapName}.{layerName} .
* `app_id` - app_id of the project creating the layer.
* `mapName` - the map into which the layer is to be uploaded. default = upload the layer into the app_id''s default map.
* `layerName` - name of layer to create/replace. The maximum length of a layer name and the permitted characters can be looked up in the service via resource `/v8/maps/serviceconfiguration`.'
required: true
schema:
type: string
- name: level
in: query
description: Specify tile size for the database for performance optimization, if not specified default tile size of 12 is used.
required: false
schema:
type: integer
format: int32
default: 12
- name: storage
in: query
description: Either updatable or readonly. Default = updatable.
required: false
schema:
type: string
default: updatable
- name: wktQuote
in: query
description: Specify the quote character to use. Specifying NONE disables quotes.
required: false
schema:
type: string
default: '"'
- name: indexColumns
in: query
description: 'Specify columns of the layer that should be indexed. Column name is followed by semi-colon(;) and indexing type. Supported indexing types are: order(o), text(t) or both - order,text(o,t). Columns are separated by pipe(|). Example &indexColumns=POI_ID;order|CAT_ID;text|ADMIN_IDS;order,text'
required: false
schema:
type: string
- name: grantedAppIds
in: query
description: Comma separated list of app_ids (in addition to the one creating the layer), which would also get access (per default read+export access) to this layer. Example `&granted_app_ids=otherAppId1,otherAppId2` .
required: false
schema:
type: string
- name: file
in: query
description: WKT file content
required: true
style: form
schema:
type: string
format: text/plain
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LayerUploadResponse'
/v8/geofence/modify:
post:
tags:
- Geofencing V8
summary: Modify Geometries in Existing Layers
description: 'Modify geometries using an HTTP POST request. After receiving the response, there is a delay of several seconds to compile, store and make the modified geometries available in the service. Note: The level (tile grid size) of the layer can only be changed by re-uploading the whole layer, not as a modification operation.'
operationId: Geofencing API v8ModifyPost
parameters:
- name: layerId
in: query
description: 'Unique identifier for the layer in the format {app_id}.{mapName}.{layerName}. app_id: app_id of the project modifying the layer; mapName: the map into which the layer is uploaded, default = upload the layer into the app_id''s default map; layerName: Name of layer to modify, the maximum length of a layer name and the permitted characters can be looked up in the service via resource ''v8/maps/serviceconfiguration''.'
required: true
schema:
type: string
- name: action
in: query
description: 'Action can be `append`, `update` or `delete`.
* Geometries are identified by their unique geometry_id column value.
* For an append operation, new geometries in requestBody must not already exist in the layer, and they will be added.
* For an update, geometries in requestBody must already exist, and these will be replaced.
* All column values must be specified, not only the changes.
* For update and delete operation, attribute columns names, sequence order and type must remain unchanged.
* For delete operation, the geometries must exist and will be removed. Only the `geometry_id` column is required for this operation.'
required: true
schema:
type: string
- name: wktQuote
in: query
description: Specify the quote character to use. Specifying NONE disables quotes.
required: false
schema:
type: string
default: '"'
- name: ownerAppId
in: query
description: Owner app_id that was used to upload a layer. It is mandatory when a granted app_id is used to access the layer.
required: false
schema:
type: string
- name: file
in: query
description: WKT file content
required: true
style: form
schema:
type: string
format: text/plain
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LayerModifyResponse'
'409':
description: Modify Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/LayerModifyResponse'
/v8/geofence/delete:
get:
tags:
- Geofencing V8
summary: Delete some of my Geometry Layers.
operationId: Geofencing API v8DeleteMapsLayers
parameters:
- name: layerId
in: query
description: 'Unique identifier for the layer in the format {app_id}.{mapName}.{layerNames}. app_id: app_id of the project under which the layers exit; mapName: delete the layers within this map, default = delete the layers in app_id''s default map; layerNames: Comma separated name of layers to delete. The maximum length of a layer name and the permitted characters can be looked up up in the service via /serviceconfiguration.json.'
required: true
schema:
type: string
- name: storage
in: query
description: Either updatable or readonly. Default = updatable. Only updatable layers can be deleted, for readonly layers and overlays complete map containing the layer should be deleted.
required: false
schema:
type: string
- name: callback
in: query
description: Specifies the function used to wrap the JSON response.
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteLayersResponse'
/v8/geofence/attributes:
get:
tags:
- Geofencing V8
summary: Simple and fast access to your custom geofence attributes
operationId: Geofencing API geofenceAttributes
parameters:
- name: app_id
in: query
required: false
schema:
type: string
- name: app_code
in: query
required: false
schema:
type: string
- name: mapName
in: query
description: map name. If not specified, the content of all maps containing the requested layer(s) is retrieved
required: false
schema:
type: string
- name: layers
in: query
description: Comma separated list of layers to be searched. Layer names are not case sensitive. The maximum length of a layer name and the permitted characters can be looked up up in the service via v8/maps/serviceconfiguration. Via the attributes parameter only certain column attributes from a layer can be returned.
required: true
schema:
type: string
- name: in
in: query
description: Supported filtering options are tile and all(full layer). The format is &in=all or &in=tile:{comma separated list of tile ids}. In case of tile search, the number of tile ids must match with the number of requested layers.
required: false
schema:
type: string
- name: filter
in: query
description: 'A SQL expression is evaluated for each geometry returned from the specified layer listing. Column values for the geometry are available as defined variables. When specified, only geometries where expression evaluates to true will be returned. Supported SQL filter operators are: ''='', ''!='', ''>'', ''<'', ''AND'', ''OR'', ''LIKE''. Example: filter=RATING > 3 AND NAME != ''MyPlace23'' AND NAME LIKE ''FOOD%''. Parameter value must be url encoded when using special characters. This filter expression is applied to all geometries, so it can become slow for big layers. To avoid service overload, filter expressions must not exceed 100 characters of text.
Note:
1. The filter expression is applied to all objects across all specified layers. Therefore, it is most likely to work as intended when a single layer is requested.
2. The filter expression is not compatible with tile search. Tile search only allows filtering results based on attribute columns. Column filtering can be used to reduce response size.'
required: false
schema:
type: string
default: ''
- name: meta
in: query
description: When set to 1 then meta info is returned in the response. The default value is 1.
required: false
schema:
type: string
default: '1'
- name: attributes
in: query
description: Semicolon separated list of column names (in uppercase) to specify which attributes shall appear in the result. If the request specifies several layers, then pass this for each layer, as a comma separated list. Default = all.
required: false
schema:
type: string
- name: count
in: query
description: The number of geometries in the response. If more geometries satisfy the search/filter criteria, they will be suppressed. It is undefined, which of the matching geometries are returned, unless this parameter is used together with offset, which sorts the results set by geometry id. Parameter can be a single value that applies to all layers, or a comma separated list equal in number to the number of layers specified in layers parameter. The maximum number of records supported within a single request can be looked up in the v8/maps/serviceconfiguration endpoint. This parameter can only be used with &in=all filter to download the custom layers.
required: false
schema:
type: string
- name: offset
in: query
description: To paginate huge responses, this parameter specifies the lowest geometry id to be returned. If geometry ids are not known, then retrieve the first page using zero, and to retrieve subsequent pages then request highest geometry of current page + 1 (it doesn't matter whether this geometry id actually exists or not). Use this parameter together with count parameter. Parameter can be a single value that applies to all layers, or a comma separated list equal in number to the number of layers specified in layers parameter. This parameter can only be used with &in=all filter to download custom layers.
required: false
schema:
type: string
- name: acceptMissingLayers
in: query
description: Optional. If this parameter is set to true, user will get list of geometries from available layers, even if some of the requested layers are missing. If none of the requested layers are found, service returns empty list.
required: false
schema:
type: string
- name: ownerAppId
in: query
description: Owner app_id that was used to upload a layer. It is mandatory when a granted app_id is used to access the layer.
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/MapAttributesV8Response'
components:
schemas:
AssetPositions:
type: object
properties:
point:
type: array
description: List of asset points with corresponding attributes.
items:
$ref: '#/components/schemas/AssetPoint'
SearchMetaResponse:
type: object
properties:
searchParameter:
type: string
writeOnly: true
layerId:
type: string
description: Layer name of geometries in a search response.
example: ADAS_ATTRIB_FC4
lastUpdateTimeStamp:
type: integer
description: last modification milli second timestamp for this layer. Only valid for custom layers, -1 for HERE map layer
format: int64
example: 1756219305792
description: List of Meta info for spatial search response.
TileRow:
type: object
properties:
columns:
type: array
description: Map of attributes and values.
example:
LINK_ID: '113421120'
LONG_HAUL: N
NAME: SR-33 / Commonwealth Ave N
NAMES: ''
TUNNEL: N
BRIDGE: N
LAT: 2831248,47,72,46,50,47,21,42,33,31
LON: -8183529,6,10,5,7,5,2,5,3,3
ZLEVEL: ',,,,,,,,,'
ELEVATION: null
TOPOLOGY_ID: '399791974'
START_OFFSET: '0'
END_OFFSET: '100000'
items:
type: string
description: Map of attributes and values.
example: '{"LINK_ID":"113421120","LONG_HAUL":"N","NAME":"SR-33 / Commonwealth Ave N","NAMES":"","TUNNEL":"N","BRIDGE":"N","LAT":"2831248,47,72,46,50,47,21,42,33,31","LON":"-8183529,6,10,5,7,5,2,5,3,3","ZLEVEL":",,,,,,,,,","ELEVATION":null,"TOPOLOGY_ID":"399791974","START_OFFSET":"0","END_OFFSET":"100000"}'
description: List of Attribute/value map from a specific layer.
AssetPoint:
type: object
properties:
lat:
type: number
description: Latitude of asset location.
format: double
lon:
type: number
description: Longitude of asset location.
format: double
layer:
type: string
description: 'Layer name to search. Layer name is case in-sensitive.
* Both custom layers and Map Attribute core map layers are supported.
* Map Attribute layers categorized by functional class, like ROAD_GEOM_FC1 to FC5, can be selected by using `FCN` notation, e.g. `ROAD_GEOM_FCN`.
* The maximum length of a layer name and the permitted characters can be looked up up in the service via `/v8/maps/serviceconfiguration`.
* Using the `attributes` parameter specific column attributes from a layer can be returned.'
searchRadius:
type: number
description: Radius around the asset location.
format: double
attributes:
type: array
description: String array of column names (in uppercase) to specify which attributes from specific layer shall appear in the result.
items:
type: string
description: String array of column names (in uppercase) to specify which attributes from specific layer shall appear in the result.
assetId:
type: string
description: "Optional. Identifier for the asset. If provided, the response will contain the assetId.\n * The maximum length of an asset id and the permitted characters can be looked up in the service via `/v8/maps/serviceconfiguration`."
description: List of asset points with corresponding attributes.
MetaResponseV8:
type: object
properties:
layerName:
type: string
description: Name of layer returned in this tile response.
example: ROAD_GEOM_FC4
tileId:
type: integer
description: Tile ID for the tile returned in this response.
format: int32
example: 22055097
level:
type: integer
description: Level for layer returned in this tile response.
format: int32
example: 12
mapRegion:
type: string
description: Map region for layer returned in this tile response.
example: WEU
mapRelease:
type: string
description: Specific map release that this layer content belongs to.
example: '25122'
description: Meta info for a specific layer.
MapAttributesV8Response:
type: object
properties:
geometries:
type: array
description: List of geometries for spatial search response.
items:
$ref: '#/components/schemas/Geometry'
meta:
type: array
description: List of Meta info for spatial search response.
items:
$ref: '#/components/schemas/SearchMetaResponse'
Tiles:
type: array
items:
$ref: '#/components/schemas/TileResponseV8'
Geometry:
type: object
properties:
attributes:
type: object
additionalProperties:
type: string
description: Map of attributes and values.
example: '{"VERTICAL_FLAGS":"1","START_OFFSET":"0","LINK_ACCURACY":"3","TOPOLOGY_ID":"84266553","CURVATURES":"320","NREFNODE_LINKCURVHEADS":"1:323:37748","HPY":"419003000,1153,1647","BUA_ROAD_VERIFIED":"Y","HPX":"124992600,1153,1647","HPZ":"10429,90,122","END_OFFSET":"63636","LINK_ID":"1211034601","BUA_ROAD":"1","SLOPES":"2987,291,-655","REFNODE_LINKCURVHEADS":"-1155506340:318:38460","HEADINGS":"38168"}'
description: Map of attributes and values.
example:
VERTICAL_FLAGS: '1'
START_OFFSET: '0'
LINK_ACCURACY: '3'
TOPOLOGY_ID: '84266553'
CURVATURES: '320'
NREFNODE_LINKCURVHEADS: 1:323:37748
HPY: 419003000,1153,1647
BUA_ROAD_VERIFIED: Y
HPX: 124992600,1153,1647
HPZ: 10429,90,122
END_OFFSET: '63636'
LINK_ID: '1211034601'
BUA_ROAD: '1'
SLOPES: 2987,291,-655
REFNODE_LINKCURVHEADS: -1155506340:318:38460
HEADINGS: '38168'
distance:
type: number
description: Straight line distance calculated to the closest geometry shape point (nearestLat, nearestLong) from the search point/polygon.
format: double
example: 69.13
nearestLat:
type: number
description: Nearest latitude on this geometry from the search point/polygon.
format: double
example: 41.90037
nearestLon:
type: number
description: Nearest longitude on this geometry from the search point/polygon.
format: double
example: 12.49933
layerId:
type: string
description: Layer name that this geometry belongs to.
writeOnly: true
example: ADAS_ATTRIB_FC4
geometry:
type: string
description: WKT string representing the geometry item.
example: MULTILINESTRING((4.80498 43.95174,4.80522 43.95196,4.80525 43.95201))
originalLat:
type: number
description: Original latitude of the asset position.
format: double
example: 41.9
originalLon:
type: number
description: Original longitude of the asset position.
format: double
example: 12.5
assetId:
type: string
description: Optional identifier of the asset.
example: asset1
geometryOverride:
type: string
writeOnly: true
geometryMode:
type: string
writeOnly: true
enum:
- NONE
- TILED
- FULL
description: List of geometries for spatial search response.
TileResponseV8:
type: object
properties:
rows:
type: array
description: List of Attribute/value map from a specific layer.
items:
$ref: '#/components/schemas/TileRow'
meta:
$ref: '#/components/schemas/MetaResponseV8'
LayerModifyResponse:
type: object
properties:
action:
type: string
description: 'Action that is used in the layer modify request: can be `append`, `update` or `delete`'
example: append
LayerUploadResponse:
type: object
properties:
storedTilesCount:
type: integer
description: Number of tiles that were created to store the uploaded layer content
format: int32
example: 20
DeleteLayersResponse:
type: object
properties:
deletedLayers:
type: array
description: List of deleted layers.
example:
- SAMPLE_LAYER
items:
type: string
description: List of deleted layers.
example: '["SAMPLE_LAYER"]'
securitySchemes:
apiKey:
type: apiKey
description: A key generated specifically to authenticate API requests. For more information on how to get an API key, see [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide).
name: apiKey
in: query
bearerTokenAuth:
type: http
description: A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information on how to get a bearer token, see the [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide).
scheme: bearer
bearerFormat: JWT
externalDocs:
description: The Developer guide and Release notes are available here.
url: https://www.here.com/docs/category/geofencing-api