Flutter地理位置定位插件what3words的使用

介绍

what3words 是一个将全球任何位置转换为三个单词的地理编码系统。这个插件 w3w-dart-wrapper 提供了对 what3words v3 API 的 Dart 封装，使得在 Flutter 应用中使用 what3words 变得非常简单。

安装

首先，你需要在 pubspec.yaml 文件中添加 what3words 依赖：

dependencies:
  what3words: 3.2.0

然后运行 flutter pub get 来安装依赖。

获取 API Key

要使用 what3words API，你需要一个 API Key。你可以通过访问 what3words 官方网站 注册并获取 API Key。

使用

导入库

在你的 Dart 文件中导入 what3words 库：

import 'package:what3words/what3words.dart';

初始化 API

使用你的 API Key 初始化 What3WordsV3 实例：

var api = What3WordsV3('your-api-key');

如果你有自己的 Enterprise Suite API Server，可以指定自定义的 URL 和头部信息：

var api = What3WordsV3.withEndpoint(
    'your-api-key', 
    'https://api.yourserver.com');

var api = What3WordsV3.withHeaders(
    'your-api-key', 
    'https://api.yourserver.com',
    {'x-header-1': 'value-1', 'x-header-2': 'value-2'});

转换坐标为 what3words 地址

将经纬度坐标转换为 what3words 地址：

var words = await api
  .convertTo3wa(Coordinates(51.508344, -0.12549900))
  .language('en')
  .execute();
print('Words: ${words.data()?.toJson()}');

转换 what3words 地址为坐标

将 what3words 地址转换为经纬度坐标：

var coordinates = await api
  .convertToCoordinates('table.book.chair')
  .execute();
print('Coordinates: ${coordinates.data()?.toJson()}');

自动建议

当用户输入不正确的 what3words 地址时，AutoSuggest 可以返回一系列可能的正确地址。它需要至少两个单词和第三个单词的第一个字符来生成建议。

var autosuggest = await api
  .autosuggest('fun.with.code')
  .nResults(3)
  .execute();
print('Autosuggest: ${autosuggest.data()?.toJson()}');

你还可以通过限制结果范围来提高建议的准确性：

var autosuggest = await api
  .autosuggest('fun.with.code')
  .clipToCountry(['gb', 'be'])
  .execute();
print('Autosuggest: ${autosuggest.data()?.toJson()}');

或者设置焦点位置：

var autosuggest = await api
  .autosuggest('fun.with.code')
  .focus(Coordinates(51.4243877, -0.34745))
  .execute();
print('Autosuggest: ${autosuggest.data()?.toJson()}');

获取网格部分

获取一个区域内的 what3words 网格部分：

var gridSection = await api
  .gridSection(Coordinates(51.515900, -0.212517), Coordinates(51.527649, -0.191746))
  .execute();
print('Grid Section: ${gridSection.data()?.toJson()}');

获取支持的语言

获取当前支持的所有语言：

var languages = await api
  .availableLanguages()
  .execute();
print('Languages: ${languages.data()?.toJson()}');

处理错误

检查 API 请求是否成功，并处理错误：

var autosuggest = await api
  .autosuggest('freshen.overlook.clo')
  .clipToCountry(['fr', 'de'])	
  .execute();

if (autosuggest.isSuccessful()) {
  // 处理成功情况
} else {
  var error = autosuggest.getError();

  if (error == What3WordsError.BAD_CLIP_TO_COUNTRY) {
    // 无效的国家限制
    print('BadClipToCountry: ${error.message}');
  }
}

正则表达式函数

这些函数可以帮助你检测和查找字符串中的 what3words 地址。

isPossible3wa

检测字符串是否可能是 what3words 地址：

void main() async {
  var api = What3WordsV3('your-api-key');

  List<String> addresses = ["filled.count.soap", "not a 3wa", "not.3wa address"];

  for (String address in addresses) {
    bool isPossible = api.isPossible3wa(address);
    print("Is '$address' a possible what3words address? $isPossible");
  }
}

findPossible3wa

在文本中查找可能的 what3words 地址：

void main() async {
  var api = What3WordsV3('your-api-key');

  List<String> texts = [
    "Please leave by my porch at filled.count.soap",
    "Please leave by my porch at filled.count.soap or deed.tulip.judge",
    "Please leave by my porch at"
  ];

  for (String text in texts) {
    List<String> possibleAddresses = api.findPossible3wa(text);
    print("Possible what3words addresses in '$text': $possibleAddresses");
  }
}

isValid3wa

验证字符串是否是有效的 what3words 地址：

void main() async {
  var api = What3WordsV3('your-api-key');

  List<String> w3w_addresses = [
    "filled.count.soap",
    "filled.count.",
    "coding.is.cool"
  ];

  for (String w3w_address in w3w_addresses) {
    var response = await api.isValid3wa(w3w_address);

    if (response.isSuccessful() && response.isValid == true) {
      print("$w3w_address is a valid what3words address");
    } else if (response.isSuccessful() && response.isValid == false) {
      print("$w3w_address is an invalid what3words address");
    } else {
      print("isValid3wa error: ${response.error?.code} - ${response.error?.message}");
    }
  }
}

示例代码

以下是一个完整的示例代码，展示了如何使用 what3words 插件进行基本的地理编码和反向地理编码操作：

import 'package:what3words/what3words.dart';

void main() async {
  // 替换为你的实际 API Key
  var api = What3WordsV3('your-api-key');

  // 将坐标转换为 what3words 地址
  var words = await api
    .convertTo3wa(Coordinates(51.508344, -0.12549900))
    .language('en')
    .execute();
  print('Words: ${words.data()?.toJson()}');

  // 将 what3words 地址转换为坐标
  var coordinates = await api
    .convertToCoordinates('table.book.chair')
    .execute();
  print('Coordinates: ${coordinates.data()?.toJson()}');

  // 自动建议
  var autosuggest = await api
    .autosuggest('fun.with.code')
    .nResults(3)
    .execute();
  print('Autosuggest: ${autosuggest.data()?.toJson()}');

  // 获取网格部分
  var gridSection = await api
    .gridSection(Coordinates(51.515900, -0.212517), Coordinates(51.527649, -0.191746))
    .execute();
  print('Grid Section: ${gridSection.data()?.toJson()}');

  // 获取支持的语言
  var languages = await api
    .availableLanguages()
    .execute();
  print('Languages: ${languages.data()?.toJson()}');
}

故障排除

如果你在使用免费计划时遇到 convert-to-coordinate 请求的错误，请检查网络面板中的错误消息 Error 402 payment required，这表示你需要升级到更高的计划：

{
    "error": {
        "code": "QuotaExceeded",
        "message": "Quota Exceeded. Please upgrade your usage plan, or contact support@what3words.com"
    }
}

更多详细信息，请访问 what3words API 计划页面。如果需要进一步的帮助，请联系 support@what3words.com。

希望这些信息对你有所帮助！如果你有任何问题或需要进一步的帮助，请随时提问。