描述

这是一个 What3Words API 的 Rust 客户端，允许您将坐标转换为三位地址，反之亦然。此客户端基于 What3Words 网站上提供的 API 文档。

此 crate 可在 crates.io 上找到，名称为 what3words。

功能

已实现以下端点

• 将坐标转换为 3 字地址；
• 将 3 字地址转换为坐标；
• 基于给定参数自动建议 3 字地址；
• 检索给定矩形内所有 what3words 方格的坐标列表，该矩形由西南和东北点的坐标定义；
• 检索可用语言和区域。

用法

初始化

导入库并创建 W3WClient 实例。

use what3words::W3WClient;

fn main {
    let w3_client = W3WClient::new("<your API key>");
}

将坐标转换为 what3words 地址

获取响应

以下代码片段获取了对 /convert-to-w3a 端点的 GET 请求的整个响应。

use what3words::{Coordinate, W3WClient, ConvertTo3WAOptions};

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let coordinates = Coordinate {
        latitude: 50.830005,
        longitude: 4.329982,
    };
    let resp = w3_client.convert_to_3wa(&coordinates, &ConvertTo3WAOptions::default());
}

此调用获取坐标 (50.830005, 4.329982) 的 what3word 地址。我们还提供了可选参数 language，将其设置为 Some("en")，这将返回我们在提供的语言中的 3 个单词值（在我们的情况下是英语，默认值）。

可选的 format 参数可以是 "json"（默认值）或 "geojson"。

区域用于指定特定语言的变体。所有支持的语言和区域都可以通过 W3WClient::available_languages() 调用获取。

获取 JSON

use what3words::{Coordinate, W3WClient, ConvertTo3WAOptions};

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let coordinates = Coordinate {
        latitude: 50.830005,
        longitude: 4.329982,
    };
    let resp = w3_client.convert_to_3wa_json(&coordinates, &ConvertTo3WAOptions::default());
}

此函数仅获取响应的 JSON 主体。此 JSON 主体为 serde_json::Value 类型，因此此调用的结果是 Result<Value, Response>。

获取字符串

只有3词地址可以被获取

use what3words::{Coordinate, W3WClient, ConvertTo3WAOptions};

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let coordinates = Coordinate {
        latitude: 50.830005,
        longitude: 4.329982,
    };
    let resp = w3_client.convert_to_3wa_string(&coordinates, &ConvertTo3WAOptions::default());
}

这将导致返回的类型为 Result<String, Response>。

将what3word地址转换为坐标

获取响应

此代码片段获取了对端点 /convert-to-coordinates 的GET调用整个响应。

use what3words::W3WClient;

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let words: &str = "fight.offer.airbag";
    let resp = w3_client.convert_to_coordinates(words, &ConvertToCoordinatesOptions::default());
}

从3词地址到坐标的转换可以这样做。在上面的示例中，我们还提供了 format 参数，但没有 locale 参数。

获取 JSON

use what3words::W3WClient;

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let words: &str = "fight.offer.airbag";
    let resp = w3_client.convert_to_coordinates_json(words, &ConvertToCoordinatesOptions::default());
}

这样我们可以获取响应体JSON，因此返回的对象类型为 Result<Value, Respones>。

获取浮点数

可以这样获取只包含浮点数的响应

use what3words::W3WClient;

fn main {
    let w3_client = W3WClient::new("<your API key>");
    let words: &str = "fight.offer.airbag";
    let resp = w3_client.convert_to_coordinates_floats(words, &ConvertToCoordinatesOptions::default());
}

这将给我们纬度和经度，格式为 f64： Result<(f64, f64), Response>

自动完成

根据提供的参数自动完成3词地址。

没有额外选项

let incomplete_three_words: &str = "fight.offer.ai";
let autosuggest_resp = w3_client.autosuggest(incomplete_three_words,
AutoSuggestOptions::default());

焦点坐标

根据提供的焦点点顺序获取自动完成建议。

let coordinates = Coordinate{
    latitude: 51.0,
    longitude: 4.0
};
let options = AutoSuggestOptions {
    focus_coordinates: Some(&coordinates),
    ..Default::default()
};
let autosuggest_resp = w3_client.autosuggest(incomplete_three_words, &options);

圆圈

获取给定圆圈内的自动完成建议。

let coordinates = Coordinate {
    latitude: 51.0,
    longitude: 4.0
};
let circle = Circle {
    centerpoint: &coordinates,
    radius: 35.0
};
let options = AutoSuggestOptions {
    circle: Some(&circle),
    ..Default::default()
};
let autosuggest_resp = w3_client.autosuggest(incomplete_three_words, &options);

国家

将自动完成限制为仅返回逗号分隔的ISO 3166-1 alpha-2国家代码大写列表中指定的国家内的结果（例如，要限制为比利时和英国，请使用clip-to-country=GB,BE）。clip-to-country也将接受小写国家代码。条目必须是两个a-z字母。警告：如果两位代码不对应于国家，则不会出错：API简单地返回无结果。

let countries = vec!["GB", "BE"];
let options = AutoSuggestOptions {
    countries: Some(&countries),
    ..Default::default()
};
let resp = w3_client.autosuggest_json(incomplete_three_words, &options);

边界框

将自动完成结果限制为由坐标指定的边界框。坐标(south_lat,west_lng)，坐标(north_lat,east_lng)，其中：south_lat小于或等于north_latwest_lng小于或等于east_lng。换句话说，纬度和经度应按照大小递增的顺序指定。允许Lng跨越本初子午线：-4,178.2,22,195.4

let coordinate_sw = Coordinate {
    latitude: -4.0,
    longitude: 178.2
};
let coordinate_ne = Coordinate {
    latitude: 22.0,
    longitude: 195.4
};
let bounding_box = BoundingBox {
    south_west: &coordinate_sw,
    north_east: &coordinate_ne
};
let options = AutoSuggestOptions {
    bounding_box: Some(&bounding_box),
    ..Default::default()
};
let resp = w3_client.autosuggest_json(incomplete_three_words, &options);

多边形

将自动完成结果限制为由逗号分隔的纬度、经度对指定的多边形。API目前限于接受最多25对。

let coordinates1 = Coordinate {
    latitude: 51.521,
    longitude: -0.343,
};
let coordinates2 = Coordinate {
    latitude: 52.6,
    longitude: 2.3324,
};
let coordinates3 = Coordinate {
    latitude: 54.234,
    longitude: 8.343,
};
let polygon: Polygon = Polygon {
    coordinates: vec![&coordinates1, &coordinates2, &coordinates3],
};
let options = AutoSuggestOptions {
    polygon: Some(&polygon),
    ..Default::default()
};
let resp = w3_client.autosuggest_json(incomplete_three_words, &options);

选项

大多数调用的大部分可选参数可以通过一些 Options 结构体提供。

• convert_to_3wa 调用的选项可以通过 ConvertTo3WAOptions 提供。
• convert-to-coordinates 调用的选项可以通过 ConvertToCoordinatesOptions 提供。
• autosuggest 调用的选项可以通过 AutoSuggestOptions 提供。
• grid_section 调用的选项可以通过 GridSectionOptions 提供。

use what3words::{AutoSuggestOptions, ConvertTo3WAOptions, ConvertToCoordinatesOptions, Coordinate, GridSectionOptions};

fn main {
    let convert_to_3wa_options1 = ConvertTo3WAOptions {
        language: Some("nl"), // If unspecified, the what3words API defaults to "en"
        ..Default::default()
    };

    let convert_to_3wa_options2 = ConvertTo3WAOptions {
        format: Some("geojson"), // If unspecified, the what3words API defaults to "json"
        language: Some("zh"),
        locale: Some("zh_tr")
    };

    let convert_to_coordinates_options1 = ConvertToCoordinatesOptions {
        format: Some("geojson"),
        ..Default::default()
    };

    let convert_to_coordinates_options2 = ConvertToCoordinatesOptions {
        format: Some("geojson"),
        locale: Some("zh_tr")
    };

    let autosuggest_options1 = AutoSuggestOptions {
        focus_coordinates: Some(&Coordinate{latitude: 51.0, longitude: 4.0}),
        countries: Some(&vec!["BE", "GB"]),
        ..Default::default()
    };

    let grid_section_options1 = GridSectionOptions {
        format: Some("geojson")
    };
}

可用语言

可以使用 available_languages 方法获取可用语言和区域设置。

可用语言响应

use what3words::W3WClient;

fn main() {
    let w3_client = W3WClient::new("<your API key>");
    let resp = w3_client.available_languages();
}

可用语言JSON

use what3words::W3WClient;

fn main() {
    let w3_client = W3WClient::new("<your API key>");
    let resp = w3_client.available_languages_json();
}