{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"39d98800-b459-472a-ad12-609c1c53bc6f","name":"TM.V2 Task Matching API Documentation (Latest)","description":"## 🔎Overview\n\nThe **Task Matching API** is designed for the business users of Google Maps Platform. To explore this API features, please contact us ([geospatial@hkmci.com](https://mailto:geospatial@hkmci.com)) to apply for your account if you don't have one yet.\n\nOnce the account set up, you can grab the API Key and include it into your request header to explore the following API features.\n\nBy sending the request with single or a batch of tasks' location, Task Matching API will check them with the geographic boundaries and enrich each task with boundaries' properies based on where it falls into.\n\nThe API provides \"HKSAR 18 District Boundary\" to all licensed users as the initial boundaries. However, you can create and manage your own geographic boundaries as a private property, then apply them to process the above task matchings.\n\n## 🎯 Getting Started\n\n1. **Contact us via** [geospatial@hkmci.com](https://mailto:geospatial@hkmci.com) **to apply your user account and API Key;**\n    \n2. **Send Task Matching API request;**\n    \n3. **Send your own boundaries to us for customized task matching.**\n    \n\n## 🔑 Secured by API Key\n\nTask Matching API is secured from unauthorized use by restricting API calls to those that provide proper **API Key**. To grab this credential, first you need to have a user account (do not have one yet? contact us via [geospatial@hkmci.com](https://mailto:geospatial@hkmci.com)), and then the details will be sent from us.\n\n#### ✔ API Key\n\nOnce you get the user account, a static API Key will be reserved for you which can be added into request header as `api-key` for processing task matching request.\n\n## 📦 Task Matching API\n\nThe API can automatically match and assign the task(s) to the boundaries/regions on which they fall into.\n\n✒️ You just need to include id, latitude & longitude pairs of tasks into `requested_json` and send it as JSON body. The tasks will be enriched with the boundaries' properties according to where they fall into and be returned as response.\n\n_\\*_<u><i>Only latitude and longitude values under WGS84 standard are accepted</i></u>\n\n✒️ You can also pass the **optional** field `filter` in JSON body to narrow down the boundaries pool. The value of `filter` should nominate both property field name and the field value in a string.\n\nThe following is an example of JSON body:\n\n``` json\n{\n    \"filter\": \"'district_id'='Q'\",\n    \"requested_json\" : [\n        {\n            \"id\": \"ORDER_1\",\n            \"lat\" : 22.316354344601745,\n            \"lng\" : 114.26030134630065\n        }\n    ]\n}\n\n ```\n\n## 🌏 Prepare Your Own Boundaries\n\nThe API enables you to process task matching with your own customized boundaries and/or boundaries' properties. To do so, firstly, you need to create/modify the boundary shapes as **\"MultiPolygon\"** and provide the proper boundary properties which will be used for task assignments. Then save the boundaries as a [GEOJSON](https://geojson.org/) file and send to us. If you are not familiar with GeoData processing, don't worry, drop your request to [geospatial@hkmci.com](https://mailto:geospatial@hkmci.com) and we can help on that.\n\n#### 📍 WGS84 Standard (EPSG: 4326)\n\n#### 📍 Boundary Properties\n\nBefore you apply your own boundaries for further task matching, you should standardize and assign some property fields to each boundary, like boundary type, boundary unique ID, boundary name, vehicle ID, etc.. The properties should be concise for tasks to inherite and for you to finalize the manifest before you pass it to your next action.\n\nThe following is an example of customized boundaries and the property fields:\n\n``` json\n{\n    \"type\": \"FeatureCollection\",\n    \"features\": [\n        {\n            \"type\": \"Feature\",        \n            \"geometry\": {\n                \"type\": \"MultiPolygon\",            \n                \"coordinates\": [[[[114.19771,22.2579],[114.19778,22.25807],[114.19779,22.25816],[114.19771,22.2579]]]]\n            },        \n            \"properties\": {\n                \"b_id\": \"2\",                    // required, unique id for boundary\n                \"b_label\": \"Wan Chai District\", // required, boundary label\n                \"r_id\": \"MCI_HK\",               // required, range id\n                \"TOWNENG\": \"Wan Chai District\", // customized on field name & value\n                \"TOWNTCN\": \"灣仔區\",             // customized on field name & value\n                \"fillColor\": \"#0d5ac1\"          // customized on field name & value\n            }\n        },    {\n            \"type\": \"Feature\",     \n            \"geometry\": {\n                \"type\": \"MultiPolygon\",            \n                \"coordinates\": [[[[114.17448,22.32665],[114.17417,22.32676],[114.17411,22.32677],[114.17399,22.32678],[114.16785,22.32652],[114.17448,22.32665]]]]\n            },        \n            \"properties\": {\n                \"b_id\": \"6\", \n                \"b_label\": \"Yau Tsim Mong District\",\n                \"r_id\": \"MCI_HK\",\n                \"TOWNENG\": \"Yau Tsim Mong District\",\n                \"TOWNTCN\": \"油尖旺區\",\n                \"fillColor\": \"#7F22F9\"\n            }\n        }\n    ]\n}\n\n ```\n\n## 📝 [We'd love to hear your feedback!](https://forms.gle/fmSfhtHxP4z7k1yU8)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"27890725","team":5229428,"collectionId":"39d98800-b459-472a-ad12-609c1c53bc6f","publishedId":"2s9YRFWAHh","public":true,"publicUrl":"https://doc.taskmatching.hkmci.com","privateUrl":"https://go.postman.co/documentation/27890725-39d98800-b459-472a-ad12-609c1c53bc6f","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"3461ff"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/04976f88-63a0-49a3-96c8-ea18831eb0b9/RnVsbCBsb2dvICh3aGl0ZSkucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"3461ff"}},{"name":"light","logo":"https://content.pstmn.io/fa6a2dea-d871-41bf-818f-b057cf7a42e8/RnVsbCBsb2dvLnBuZw==","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"3461ff"}}]}},"version":"8.11.4","publishDate":"2023-10-27T08:23:58.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/fa6a2dea-d871-41bf-818f-b057cf7a42e8/RnVsbCBsb2dvLnBuZw==","logoDark":"https://content.pstmn.io/04976f88-63a0-49a3-96c8-ea18831eb0b9/RnVsbCBsb2dvICh3aGl0ZSkucG5n"}},"statusCode":200},"environments":[{"name":"PROD","id":"858488bb-933d-4928-9725-1f6b67038cb5","owner":"27890725","values":[{"key":"BASE_URL","value":"https://taskmatching.hkmci.com/","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/47838b3f31a6d444fdf4adc66d5ed8ff89adf1c18309f7c00a88894712ac2f99","favicon":"https://hkmci.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"PROD","value":"27890725-858488bb-933d-4928-9725-1f6b67038cb5"}],"canonicalUrl":"https://doc.taskmatching.hkmci.com/view/metadata/2s9YRFWAHh"}