设置家与公司

本文介绍如何将 POI 或地址设置为用户的家（HOME）或公司（WORK）地址。

前置阅读：概述、收藏 POI

基本介绍

家与公司地址是系统预定义的 Marker，分别对应 SystemMarker.HOME 和 SystemMarker.WORK。与通用收藏（FAVORITE）不同：

无需创建 Marker，直接使用系统枚举名称作为 markerId。
通常各对应唯一地址，重复设置会覆盖原有 Item。
应用层建议在覆盖前提示用户确认。

设置家/公司地址的 API 与收藏 POI 相同，均为 markItem，仅 markerId 不同。

系统 Marker 说明

Marker	枚举值	说明
家地址	`SystemMarker.HOME`	用户家庭住址
公司地址	`SystemMarker.WORK`	用户工作地址

其他常用系统 Marker（供参考）：

Marker	说明
`FAVORITE`	通用收藏，见收藏 POI
`RECENT_STOP`	最近停留地点
`NAVIGATED`	曾导航过的地点

设置流程

搜索/选点 → 构造 Item → markItem(HOME 或 WORK) → （可选）sync

用户通过搜索或地图选点确定家/公司地址。
将地址信息封装为 Item（type = ENTITY，correlationId 来自搜索结果）。
调用 markItem，markerId 设为 HOME 或 WORK，markerType 设为 SYSTEM。
按需调用 sync 同步至云端。

API 说明

使用 markItem，关键参数如下：

方法	家地址	公司地址
`setMarkerId`	`SystemMarker.HOME.name()`	`SystemMarker.WORK.name()`
`setMarkerType`	`MarkerType.SYSTEM`	`MarkerType.SYSTEM`
`setItem`	含地址/POI 信息的 `Item`	同上

其余参数（secureToken、applicationId、applicationSignature、needSync）与收藏 POI 一致。

代码示例

设置家地址

import com.telenav.user.UserServiceAPI;
import com.telenav.user.vo.*;

// 构造 Item（数据来自搜索或选点结果）
Item item = new Item();
item.setCorrelationId(searchResult.getEntityId());
item.setName(searchResult.getName());
item.setType(ItemType.ENTITY);
item.setMetadata(searchResult.getMetadata());
item.setModifiedUtcTimestamp(System.currentTimeMillis());

// 设为家地址
MarkResponse response = UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.HOME.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

设置公司地址

将 markerId 替换为 SystemMarker.WORK.name() 即可：

MarkResponse response = UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.WORK.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

查询当前家/公司地址

通过 listItems 按 Marker 查询，详见查询与管理。

// 查询家地址
ListItemsResponse homeResponse = UserServiceAPI.getItemMarkAPI()
    .listItems()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemType(ItemType.ENTITY)
    .setMarkerId(SystemMarker.HOME.name())
    .setMarkerType(MarkerType.SYSTEM)
    .execute();

同时设为收藏和家地址

同一 POI 可关联多个 Marker，分别调用 markItem：

// 先设为家地址
UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.HOME.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

// 再加入收藏夹
UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

注意事项

覆盖行为：HOME 和 WORK 通常各只保留一个地址，新设置会覆盖旧地址。建议在 UI 层提示用户确认。
correlationId 来源：与收藏 POI 相同，应使用搜索 API 返回的实体 ID。
离线支持：离线时可写入本地，联网后通过 sync 同步，参见查询与管理。
取消设置：通过 unmarkItem 取消家/公司地址关联，参见查询与管理。