Search Results
Found 0 result(s) for ""
Search results are affected by your filter settings.
This page does NOT support Internet Explorer. Please use a modern browser like e.g. Google Chrome, Mozilla Firefox or Microsoft Edge.
IntroductionCopied link to clipboard
This section describes the Map API endpoints that provides developers with comprehensive access to real-time spatial mapping, positioning, and cleaning history features of connected cleaning robots. Through this set of REST API endpoints, developers can programmatically read the mapping features of a home appliance, access grid and vector map data, retrieve custom boundaries, track active cleaning paths, and review historic session summaries.
Availability
The API features described in this section are exclusively available for the cleaning robot Bosch Spotless. Please note that they are not supported by the previous cleaning robot model, Bosch Roxxter.
The map endpoints are available in all regions in which Home Connect operates, with the exception of China.
Authorization
Access to all endpoints in this section requires the scope CleaningRobot or only CleaningRobot-Map. This scope is not included in the Monitor group-scope.
See Authorization Scopes for details.
Base path
All map resources are located below https:/
Response format
The map endpoints return plain application/json and do not wrap their payload in a data object. A response is either a JSON object or, in case of the list endpoints, a JSON array at top level. The vendor media type application/vnd.bsh.sdk.v1+json used by the other resources is not required here.
Error responses are sent as application/problem+json and follow the problem details format defined in RFC 7807:
{
"type": "https://errors.home-connect.com/map-not-found",
"title": "Map data not found",
"status": 404,
"detail": "The home appliance has not stored a map with id 7."
}
Coordinate system
All geometry is expressed in one cartesian coordinate system per map:
- Coordinates are given in centimeters.
- The x coordinate increases rightwards, the y coordinate increases upwards.
- An orientation angleX is given in degrees, starting at 0 in positive x-axis direction and increasing counter-clockwise.
Larger geometries are transferred in compressed form on some home appliances. Where this applies, the response contains either the plain field (for example gridMap) or its compressed counterpart (for example gridMapCompressedZstd), never both. Compressed fields are zstd compressed and base64url encoded.
Related resources (Roxxter only)
The cleaning robot exposes further map-related information through the regular appliance resources. Please note that the following settings, status and option are only supported by the Roxxter series and are therefore not available on the home appliances which support the endpoints described in this section:
- Setting Current Map - ConsumerProducts.CleaningRobot.Setting.CurrentMap
- Setting Names of Maps - ConsumerProducts.CleaningRobot.Setting.NameOfMap1 to NameOfMap3
- Status Last Selected Map - ConsumerProducts.CleaningRobot.Status.LastSelectedMap
- Option Reference Map ID Option - ConsumerProducts.CleaningRobot.Option.ReferenceMapId
Supported FeaturesCopied link to clipboard
By integrating with the Map API, client applications can utilize the following capabilities:
- Map Retrieval: Fetch basic metadata and coordinate frames of saved or temporary maps.
- Low-Level Occupancy Grids: Download raw grid-based occupancy data (including a compressed option) to render high-resolution 2D structural maps.
- Vector Layout Details: Access structural vectors detailing physical barriers like walls (inner and outer walls) and doors.
- Live Positioning & Tracking: Track the exact horizontal and vertical coordinate position (x, y) and rotation angle in degrees of the robot in real time.
- Active Cleaning Paths: Monitor live spatial coverage and paths traversed by the appliance during an active cycle.
- AI Object Detection: Identify and retrieve details about detected obstacles, pets, and localized stain types (such as dry, heavy, mixed, particles, or liquid stains) with confidence ratings and media attachments.
- Room Segmentation: Retrieve room divisions, custom room names, floor types (such as carpet or hardwood), and room inter-connectivity.
- Keep-Out & Restricted Areas (Zones): Fetch virtual boundaries including No-Go Zones, No-Mop Zones, No-Go Barriers, and No-Mop Barriers.
- Operational Restrictions: Query runtime permissions concerning map edit-ability, room merges/splits, and zone limits.
- Session Summaries: Access archived historical sessions detailing past structural maps, paths, and detected objects.
Resource overview
Get a list of mapsCopied link to clipboard
Retrieves all maps with their basic information.
This endpoint returns the list of maps known to the cleaning robot, identified by its unique haId. Each map includes basic details such as its identifier, a user-defined name and the positions of the base stations. It also indicates whether a map is temporary or fully saved.
Map names are empty until the user actively sets a custom name in Home Connect app. If the name is empty, the app UI shows a default fallback that is not reflected in the response from MAP endpoints.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON array with the maps known to the cleaning robot. A home appliance without any map returns an empty array.
Example
GET https:/
[
{
"mapId": 1,
"name": "Ground floor",
"isSaved": true,
"baseStations": [
{
"x": 120,
"y": -35,
"angleX": 90
}
]
},
{
"mapId": 2,
"name": "First floor",
"isSaved": true,
"baseStations": []
},
{
"mapId": 3,
"name": "",
"isSaved": false,
"baseStations": []
}
]
HTTP Status Code
Get a specific mapCopied link to clipboard
Retrieves the basic information of one map.
This endpoint returns the same data as the list endpoint, but only for the map identified by mapId.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the basic data of the requested map.
Example
GET https:/
{
"mapId": 1,
"name": "Ground floor",
"isSaved": true,
"baseStations": [
{
"x": 120,
"y": -35,
"angleX": 90
}
]
}
HTTP Status Code
Get the occupancy grid of a mapCopied link to clipboard
Retrieves the grid based raw layout of a map.
The occupancy grid is the pixel representation of the area the robot has explored. It is packed as an array in row-major order, starting on the bottom left grid cell. Together with width, height, resolution and origin it can be rendered directly as a bitmap.
Depending on the home appliance, the grid is delivered either as a plain integer array in gridMap or zstd compressed and base64url encoded in gridMapCompressedZstd. Exactly one of the two fields is present.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the occupancy grid of the requested map.
Example
GET https:/
{
"mapId": 1,
"resolution": 5,
"width": 6,
"height": 4,
"origin": {
"x": -250,
"y": -180,
"angleX": 0
},
"gridMap": [
2, 2, 2, 2, 2, 2,
2, 1, 1, 1, 1, 2,
2, 1, 1, 1, 1, 2,
2, 2, 2, 2, 2, 2
]
}
HTTP Status Code
Get the layout of a mapCopied link to clipboard
Retrieves the vector based layout of a map.
In contrast to the occupancy grid, the layout describes the walls and doors of the mapped area as typed paths. A layout consists of one or more layout areas; each layout area is enclosed in a series of wall and door segments.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the layout of the requested map.
Example
GET https:/
{
"mapId": 1,
"layoutAreas": [
{
"layoutId": 1,
"layout": [
{
"type": "OuterWall",
"path": [
{ "x": -250, "y": -180 },
{ "x": 250, "y": -180 },
{ "x": 250, "y": 180 },
{ "x": -250, "y": 180 },
{ "x": -250, "y": -180 }
]
},
{
"type": "InnerWall",
"path": [
{ "x": 20, "y": -180 },
{ "x": 20, "y": 40 }
]
},
{
"type": "DoorInwardsRight",
"path": [
{ "x": 20, "y": 40 },
{ "x": 20, "y": 120 }
]
}
]
}
]
}
HTTP Status Code
Get the cleaning status of a mapCopied link to clipboard
Retrieves the cleaning information of the current or last cleaning run on a map.
The main content is the cleaning path, i.e. the track the robot has already driven. It can be rendered on top of the occupancy grid or the layout to visualize the cleaning progress.
Depending on the home appliance, the path is delivered either as a plain list of points in cleaningPath or zstd compressed and base64url encoded in cleaningPathCompressedZstd.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the cleaning status of the requested map.
Example
GET https:/
{
"mapId": 1,
"cleaningPath": [
{ "x": 120, "y": -35 },
{ "x": 118, "y": 10 },
{ "x": 115, "y": 62 },
{ "x": 90, "y": 104 },
{ "x": 44, "y": 121 }
]
}
HTTP Status Code
Get a list of detected objectsCopied link to clipboard
Retrieves all objects which the cleaning robot has detected on a map.
Detected objects are things the robot recognized while cleaning, for example a stain or a pet. Each object carries its position on the map, a type, a display status and the confidence of the recognition. If the robot took a picture of the object, an imageId is provided as well.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON array with the objects detected on the requested map. If nothing has been detected, the array is empty.
Example
GET https:/
[
{
"mapId": 1,
"objectId": 1,
"position": {
"x": 82,
"y": -14
},
"type": "Service.Map.ObjectType.Stain.Water",
"status": "Shown",
"confidence": 0.87,
"imageId": "1f5b2e0c-9a4d-4f61-b0a2-6c3d7e8f9012"
},
{
"mapId": 1,
"objectId": 2,
"position": {
"x": -140,
"y": 96
},
"type": "Service.Map.ObjectType.Pet",
"status": "HiddenOnce",
"confidence": 0.62
}
]
HTTP Status Code
Get a specific detected objectCopied link to clipboard
Retrieves one object which the cleaning robot has detected on a map, identified by objectId.
HTTP Method
GET
URL
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the details of the requested detected object.
Example
GET https:/
{
"mapId": 1,
"objectId": 1,
"position": {
"x": 82,
"y": -14
},
"type": "Service.Map.ObjectType.Stain.Water",
"status": "Shown",
"confidence": 0.87,
"imageId": "1f5b2e0c-9a4d-4f61-b0a2-6c3d7e8f9012"
}
HTTP Status Code
Get a list of roomsCopied link to clipboard
Retrieves all rooms which are defined on a map.
Rooms are the areas the user has cut out of a saved map. Each room carries its reachable area as a path of points, and optionally a user-defined name, a floor type and a room type. Rooms are the basis for the room-based cleaning programs.
Room names are empty until the user actively sets a custom name in Home Connect app. If the name is empty, the app UI shows a default fallback that is not reflected in the response from MAP endpoints.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON array with the rooms defined on the requested map. A map which has not been divided into rooms returns an empty array.
Example
GET https:/
[
{
"mapId": 1,
"roomId": 1,
"name": "Living room",
"floorType": "Service.Map.FloorType.Carpet",
"roomType": "Service.Map.RoomType.LivingRoom",
"connectedRooms": [2],
"reachableArea": [
{ "x": -250, "y": -180 },
{ "x": 20, "y": -180 },
{ "x": 20, "y": 180 },
{ "x": -250, "y": 180 }
]
},
{
"mapId": 1,
"roomId": 2,
"floorType": "Service.Map.FloorType.Unspecified",
"roomType": "Service.Map.RoomType.Room",
"connectedRooms": [1],
"reachableArea": [
{ "x": 20, "y": -180 },
{ "x": 250, "y": -180 },
{ "x": 250, "y": 180 },
{ "x": 20, "y": 180 }
]
}
]
HTTP Status Code
Get a specific roomCopied link to clipboard
Retrieves one room of a map, identified by roomId.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the details of the requested room.
Example
GET https:/
{
"mapId": 1,
"roomId": 1,
"name": "Living room",
"floorType": "Service.Map.FloorType.Carpet",
"roomType": "Service.Map.RoomType.LivingRoom",
"connectedRooms": [2],
"reachableArea": [
{ "x": -250, "y": -180 },
{ "x": 20, "y": -180 },
{ "x": 20, "y": 180 },
{ "x": -250, "y": 180 }
]
}
HTTP Status Code
Get a list of zonesCopied link to clipboard
Retrieves all zones and virtual barriers which are defined on a map.
There are 2 types of zones.
Zones restrict where and how the robot cleans. The geometry depends on the zone type: barriers are described by a line, zones are described by a rectangle.
Zones for the "Zone Cleaning" program are not provided via MAP endpoint, but they are accessible via program option ConsumerProducts.CleaningRobot.Option.Zones.
The zones which are virtual boundaries and No-Go zones are configured in the Home Connect app in the edit map screen via the "hand" button, which is located in the bottom right of that view.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON array with the zones defined on the requested map. A map without zones returns an empty array.
Example
GET https:/
[
{
"mapId": 1,
"zoneId": 1,
"zoneType": "Service.Map.ZoneType.NoGoZone",
"rectangle": {
"x1": -120,
"y1": 140,
"x2": -40,
"y2": 60
}
},
{
"mapId": 1,
"zoneId": 2,
"zoneType": "Service.Map.ZoneType.NoMopBarrier",
"line": {
"x1": 20,
"y1": 40,
"x2": 20,
"y2": 120
}
}
]
HTTP Status Code
Get a specific zoneCopied link to clipboard
Retrieves one zone or virtual barrier of a map, identified by zoneId.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the details of the requested zone.
Example
GET https:/
{
"mapId": 1,
"zoneId": 1,
"zoneType": "Service.Map.ZoneType.NoGoZone",
"rectangle": {
"x1": -120,
"y1": 140,
"x2": -40,
"y2": 60
}
}
HTTP Status Code
Get the position of the robotCopied link to clipboard
Retrieves the current position and orientation of the cleaning robot together with the map it is currently located on.
As long as the robot has not found its location, mapId can be null or omitted and isValid is false. In that case the robot needs to re-localize and the reported position must not be displayed as its actual position.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the current position of the cleaning robot.
Example
GET https:/
{
"mapId": 1,
"position": {
"x": 44,
"y": 121,
"angleX": 187.5
},
"isValid": true
}
HTTP Status Code
Get the map configuration restrictionsCopied link to clipboard
Retrieves the restrictions of the home appliance regarding maps, rooms and zones.
The restrictions tell you which map properties the home appliance supports, which values are allowed and whether editing is currently possible. Evaluate them before you offer map, room or zone configuration in your application, instead of hard-coding limits per appliance model.
If a property is not present in the response, the default described in the table below applies.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the configuration restrictions of the home appliance.
Example
GET https:/
{
"room.floorType.supported": true,
"room.floorType.allowedValues": [
"Service.Map.FloorType.Unspecified",
"Service.Map.FloorType.Carpet",
"Service.Map.FloorType.HardFloor"
],
"room.roomType.allowedValues": [
"Service.Map.RoomType.Room",
"Service.Map.RoomType.LivingRoom",
"Service.Map.RoomType.Kitchen",
"Service.Map.RoomType.Bedroom",
"Service.Map.RoomType.Bathroom"
],
"maps.isSaved.maxCount": 5,
"maps.editable": true,
"maps.rooms.editable": true,
"maps.rooms.splitmerge.editable": false,
"maps.zones.maxCount": 20,
"maps.zones.editable": true
}
HTTP Status Code
Get a list of cleaning summariesCopied link to clipboard
Retrieves the summaries of the cleaning runs which are stored on the home appliance.
A cleaning summary is a snapshot of one cleaning run. It contains the map data exactly as it was at the time of that run, so you can render a past run without having to reconstruct the map from the current resources.
Depending on what the home appliance supports, the map of the run is described either by occupancyGrid or by the combination of layout, rooms and zones.
Please note that this endpoint returns the full data of every stored run. If you only need one run, use Get a specific cleaning summary.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON array with the cleaning summaries stored on the home appliance.
Example
GET https:/
[
{
"counter": 41,
"map": {
"mapId": 1,
"name": "Ground floor",
"isSaved": true,
"baseStations": [
{ "x": 120, "y": -35, "angleX": 90 }
]
},
"layout": {
"mapId": 1,
"layoutAreas": [
{
"layoutId": 1,
"layout": [
{
"type": "OuterWall",
"path": [
{ "x": -250, "y": -180 },
{ "x": 250, "y": -180 },
{ "x": 250, "y": 180 },
{ "x": -250, "y": 180 },
{ "x": -250, "y": -180 }
]
}
]
}
]
},
"rooms": [
{
"mapId": 1,
"roomId": 1,
"name": "Living room",
"floorType": "Service.Map.FloorType.Carpet",
"roomType": "Service.Map.RoomType.LivingRoom",
"connectedRooms": [],
"reachableArea": [
{ "x": -250, "y": -180 },
{ "x": 20, "y": -180 },
{ "x": 20, "y": 180 },
{ "x": -250, "y": 180 }
]
}
],
"zones": [],
"cleaningStatus": {
"mapId": 1,
"cleaningPath": [
{ "x": 120, "y": -35 },
{ "x": 90, "y": 104 },
{ "x": 44, "y": 121 }
]
},
"cleaningStatus.objects": [
{
"mapId": 1,
"objectId": 1,
"position": { "x": 82, "y": -14 },
"type": "Service.Map.ObjectType.Stain.Water",
"status": "Shown",
"confidence": 0.87
}
],
"robot.position": {
"mapId": 1,
"position": { "x": 120, "y": -35, "angleX": 90 },
"isValid": true
}
}
]
HTTP Status Code
Get a specific cleaning summaryCopied link to clipboard
Retrieves the summary of one cleaning run, identified by its counter.
The counter is an incremental number which uniquely identifies a cleaning run summary on the home appliance. You get the available counters from Get a list of cleaning summaries.
HTTP Method
GET
URL
https:/
Required Scope
CleaningRobot-Map
Query Parameters
Endpoint Response
The request will return a JSON object with the details of the requested cleaning summary.
Example
GET https:/
{
"counter": 41,
"map": {
"mapId": 1,
"name": "Ground floor",
"isSaved": true,
"baseStations": [
{ "x": 120, "y": -35, "angleX": 90 }
]
},
"occupancyGrid": {
"mapId": 1,
"resolution": 5,
"width": 6,
"height": 4,
"origin": {
"x": -250,
"y": -180,
"angleX": 0
},
"gridMap": [
2, 2, 2, 2, 2, 2,
2, 1, 1, 1, 1, 2,
2, 1, 1, 1, 1, 2,
2, 2, 2, 2, 2, 2
]
},
"cleaningStatus": {
"mapId": 1,
"cleaningPath": [
{ "x": 120, "y": -35 },
{ "x": 90, "y": 104 },
{ "x": 44, "y": 121 }
]
},
"cleaningStatus.objects": [],
"robot.position": {
"mapId": 1,
"position": { "x": 120, "y": -35, "angleX": 90 },
"isValid": true
}
}