# Motion service API

The motion service API allows you to give commands to your [motion service](https://docs.viam.com/reference/services/motion/) for moving a mobile robot based on a SLAM map or GPS coordinates or for moving a machine’s components from one pose to another.

The motion service supports the following methods:

| Method Name | Description |
| --- | --- |
| [`Move`](https://docs.viam.com/reference/apis/services/motion/#move) | The `Move` method is the primary way to move multiple components, or to move any object to any other location. |
| [`MoveOnMap`](https://docs.viam.com/reference/apis/services/motion/#moveonmap) | Move a base component to a destination pose on a SLAM map. |
| [`MoveOnGlobe`](https://docs.viam.com/reference/apis/services/motion/#moveonglobe) | Move a base component to a destination GPS point, represented in geographic notation _(latitude, longitude)_. |
| [`GetPose`](https://docs.viam.com/reference/apis/services/motion/#getpose) | `GetPose` gets the location and orientation of a component within the frame system. |
| [`StopPlan`](https://docs.viam.com/reference/apis/services/motion/#stopplan) | Stop a base component being moved by an in progress `MoveOnGlobe` or `MoveOnMap` call. |
| [`ListPlanStatuses`](https://docs.viam.com/reference/apis/services/motion/#listplanstatuses) | Returns the statuses of plans created by `MoveOnGlobe` or `MoveOnMap` calls that meet at least one of the following conditions since the motion service initialized: - the plan’s status is in progress - the plan’s status changed state within the last 24 hours All repeated fields are in chronological order. |
| [`GetPlan`](https://docs.viam.com/reference/apis/services/motion/#getplan) | By default, returns the plan history of the most recent `MoveOnGlobe` or `MoveOnMap` call to move a base component. |
| [`Reconfigure`](https://docs.viam.com/reference/apis/services/motion/#reconfigure) | Reconfigure this resource. |
| [`FromRobot`](https://docs.viam.com/reference/apis/services/motion/#fromrobot) | Get the resource from the provided machine. |
| [`DoCommand`](https://docs.viam.com/reference/apis/services/motion/#docommand) | Execute model-specific commands that are not otherwise defined by the service API. |
| [`GetResourceName`](https://docs.viam.com/reference/apis/services/motion/#getresourcename) | Get the `ResourceName` for this instance of the motion service. |
| [`Close`](https://docs.viam.com/reference/apis/services/motion/#close) | Safely shut down the resource and prevent further use. |

## API

### Move

The `Move` method is the primary way to move multiple components, or to move any object to any other location. Given a destination pose and a component to move to that destination, `Move` will:

1. Construct a full kinematic chain from goal to destination including all movable components in between.
2. Solve that chain to move the specified component frame to the destination while adhering to any constraints.
3. Execute that movement to move the actual machine.
4. Return whether or not this process succeeded.

The motion service takes the volumes associated with all configured machine components (local and remote) into account for each request to ensure that the machine does not collide with itself or other known objects.

- [Python](https://docs.viam.com/reference/apis/services/motion/#tabset-referenceapisservicesmotion-1-0)
- [Go](https://docs.viam.com/reference/apis/services/motion/#tabset-referenceapisservicesmotion-1-1)
- [TypeScript](https://docs.viam.com/reference/apis/services/motion/#tabset-referenceapisservicesmotion-1-2)

**Parameters:**

- `component_name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The `ResourceName` of the piece of the robot that should arrive at the destination. Note that `move` moves the distal end of the component to the destination. For example, when moving a robotic arm, the piece that will arrive at the destination is the end effector attachment point, not the base of the arm.

- `destination` ( [viam.proto.common.PoseInFrame](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame)) (required): Describes where the `component_name` frame should be moved to. Can be any pose, from the perspective of any component whose location is configured as a [`frame`](https://docs.viam.com/motion-planning/frame-system/).

- `world_state` ( [viam.proto.common.WorldState](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.WorldState)) (optional): Data structure specifying information about the world around the machine. Used to augment the motion solving process.

- `constraints` ( [viam.proto.service.motion.Constraints](https://python.viam.dev/autoapi/viam/proto/service/motion/index.html#viam.proto.service.motion.Constraints)) (optional): Pass in [motion constraints](https://docs.viam.com/reference/services/motion/constraints/). By default, motion is unconstrained with the exception of obstacle avoidance.

- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.

- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- ( [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)): Whether the move was successful (`true`) or unsuccessful (`false`).

### MoveOnMap

#### Not supported by the builtin motion service

The [builtin motion service](https://docs.viam.com/reference/services/motion/) no longer implements `MoveOnMap` and returns the error `MoveOnMap not supported by builtin` when called. The implementation was removed in [rdk#5475](https://github.com/viamrobotics/rdk/pull/5475) (November 2025).

`MoveOnMap` is still part of the motion service API, so a third-party module can implement it. Check the [Viam registry](https://app.viam.com/registry) for a motion-service module that supports it before relying on this method.

### MoveOnGlobe

Move a [base](https://docs.viam.com/reference/components/base/) component to a destination GPS point, represented in geographic notation _(latitude, longitude)_. Use a [movement sensor](https://docs.viam.com/reference/components/movement-sensor/) to check the location of the machine.

`MoveOnGlobe()` is non blocking, meaning the motion service will move the component to the destination GPS point after `MoveOnGlobe()` returns.

Each successful `MoveOnGlobe()` call returns a unique `ExecutionID` which you can use to identify all plans generated during the `MoveOnGlobe()`.

### GetPose

`GetPose` gets the location and orientation of a component within the [frame system](https://docs.viam.com/motion-planning/frame-system/). The return type of this function is a `PoseInFrame` describing the pose of the specified component with respect to the specified destination frame.

### StopPlan

Stop a [base](https://docs.viam.com/reference/components/base/) component being moved by an in progress [`MoveOnGlobe`](https://docs.viam.com/reference/apis/services/motion/#moveonglobe) or [`MoveOnMap`](https://docs.viam.com/reference/apis/services/motion/#moveonmap) call.

### ListPlanStatuses

Returns the statuses of plans created by [`MoveOnGlobe`](https://docs.viam.com/reference/apis/services/motion/#moveonglobe) or [`MoveOnMap`](https://docs.viam.com/reference/apis/services/motion/#moveonmap) calls that meet at least one of the following conditions since the motion service initialized:
- the plan’s status is in progress
- the plan’s status changed state within the last 24 hours

### GetPlan

By default, returns the plan history of the most recent [`MoveOnGlobe`](https://docs.viam.com/reference/apis/services/motion/#moveonglobe) or [`MoveOnMap`](https://docs.viam.com/reference/apis/services/motion/#moveonmap) call to move a [base](https://docs.viam.com/reference/components/base/) component.

### Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

### FromRobot

Get the resource from the provided machine.

### DoCommand

Execute model-specific commands that are not otherwise defined by the service API.

### GetResourceName

Get the `ResourceName` for this instance of the motion service.

### Close

Safely shut down the resource and prevent further use.