README

Spot Tracker Shared Page API的PHP客户端。

关于API

尽管它没有过度宣传，但有一个免费的公共数据源可供Spot Trackers使用，提供过去7天内每个设备的详细跟踪数据。

相对较少的文档在此处可用：http://faq.findmespot.com/index.php?action=showEntry&data=69

此API提供的信息与用户在其Spot共享页面上看到的信息相同。

此API返回的数据以XML或JSON编码，具体取决于请求URI。

某些数据源受密码保护，调用者必须传递一个匹配的密码才能检索数据。

API请求类型

API支持两种类型的数据源：最新和消息。

最新消息请求

返回来自数据源的最新的（单个）位置数据。由于此调用结果是一个单一的消息，因此没有对结果进行过滤或分页。

如果只需要知道在某个特定时间点的设备位置，这非常有用。

use TravisAMiller\SpotTrackerApi\ApiClient;

$client = new ApiClient('your-feed-id-here');

$result = $client->latest();

$result->getFeed();     // Details about data feed.
$result->getMessages(); // Array of all messages received -- only one for this endpoint.
$result->getMessage();  // Direct accesss to message recevied from this endpoint.

消息数据源请求

根据调用者提供的（可选）标准返回一系列消息。消息由远程服务器自动分页为每50条结果集。

此外，还可以对消息数据源应用某些过滤器。

use TravisAMiller\SpotTrackerApi\ApiClient;

$client = new ApiClient('your-feed-id-here');

// retrieve messages on the first page of results, any date range.
$result = $client->messages();

// retrieve messages on the second page of results.
$result = $client->messages([
    'start' => 50
]);

// only retrieve messages newer than midnight yesterday.
$result = $client->messages([
    'startDate' => new DateTime('yesterday midnight')
]);

// only retrieve messages since older than midnight today.
$result = $client->messages([
    'endDate' => new DateTime('today midnight')
]);

// retrieve message from yesterday on the third page.
$result = $client->messages([
    'start' => 100, // 0 = first age, 50 = second page, 100 = third page
    'startDate' => new DateTime('yesterday midnight'),
    'endDate' => new DateTime('today midnight')
]);

响应包含一些方法，使分页更加容易。

use TravisAMiller\SpotTrackerApi\ApiClient;

$client = new ApiClient('your-feed-id-here');

$result = $client->messages([
    'start' => 50
]);

$result->hasNextPage(); // true if there are more than 100 results.
$result->hasPreviousPage() // true if there the current position isn't the first page.

$request = $result->getNextPageRequest(); // get request for next page of results.
$request = $result->getPreviousPageRequest(); // get request for last page of results.

$result = $client->send($request); // gets results for either request above.

以下代码将检索API中所有可用的消息：

use TravisAMiller\SpotTrackerApi\ApiClient;

$client = new ApiClient('your-feed-id-here');

$page = $client->messages();
do {
    if ($page->hasErrors()) {
        foreach($page->getErrors() as $error) {
            printf(
                "Error: %s (%s)",
                $error->getDescription(),
                $error->getCode()
            );
        }
        break;
    }

    foreach ($page->getMessages() as $message) {
        printf(
            "Location: %F %F (ID: %d)\n",
            $message->getLatitude(),
            $message->getLongitude(),
            $message->getId()
        );
    }
} while (
    $page->hasNextPage() &&
    $page = $client->send($page->getNextPageRequest())
);

自定义请求过滤器

除了提供请求过滤器作为数组外

$result = $client->messages([
    'start' => 50
]);

还可以直接传递请求过滤器

$yesterday = new MessagesFilter([
    'startDate' => new DateTime("yesterday midnight"),
    'endDate' => new DateTime("today midnight"),
]);

$results = $client->messages($yesterday);

这允许在多个请求中重用过滤器。