{ "openapi": "3.1.0", "info": { "title": "what3words API", "x-postman-collection-url": "https://openapi.what3words.com/what3words.postman_collection.json", "license": { "name": "what3words API License", "url": "https://www.what3words.com/terms" }, "description": "The what3words API provides a simple and powerful interface to interact with the what3words addressing system. \nIt allows you to convert between what3words addresses and geographic coordinates, validate and autocorrect user input, \nand retrieve information about supported languages and the what3words grid.\n\nKey features include:\n- **Convert to what3words address**: Convert latitude and longitude coordinates into a what3words address.\n- **Convert to coordinates**: Convert a what3words address into latitude and longitude coordinates.\n- **AutoSuggest**: Suggest valid what3words addresses based on partial or incorrect input, with options to prioritize results by location or restrict results to specific areas. \n- **AutoSuggest with Coordinates**: Similar to AutoSuggest, but returns coordinates in the response. This endpoint requires special permissions, please contact [support@what3words.com](mailto:support@what3words.com) for more information.\n- **Grid Section**: Retrieve a section of the what3words grid for a specified bounding box, useful for map visualizations.\n- **Available Languages**: Get a list of all supported languages, including language codes (including script-specific variants) and native names.\n\nFor more details, visit the [what3words Public API Documentation](https://developer.what3words.com/public-api/docs#overview).\n\n**Run in Postman:** \n\n \"Run\n \n\n**Additional resources:**\n- [API Authentication](https://accounts.what3words.com/select-plan?referrer=/public-api/docs)\n- [Error Codes](https://developer.what3words.com/public-api/docs#error-handling)\n- [Supported Languages](https://developer.what3words.com/public-api/docs#available-languages)\n- [Rate Limits](https://developer.what3words.com/public-api/docs#rate-limits)\n- [API Terms of Use](https://developer.what3words.com/public-api/docs#terms-of-use)\n- [API Pricing](https://accounts.what3words.com/select-plan?referrer=/public-api/docs)\n- [Postman Collection](https://openapi.what3words.com/what3words.postman_collection.json)\n- [Blog: Minimum word and address lengths (code points vs characters)](https://what3words.com/news/blog/minimum-word-and-address-lengths-in-what3words-code-points-vs-characters)\n- [Blog: Understanding locales in what3words](https://what3words.com/news/blog/understanding-locales-in-what3words)\n- [Blog: Demystifying the alias parameter](https://what3words.com/news/blog/demystifying-the-alias-parameter-in-what3words-address-urls)\n- [Blog: LTR and RTL scripts](https://what3words.com/news/blog/how-what3words-addresses-work-in-left-to-right-ltr-and-right-to-left-rtl-scripts)\n- [Blog: Secondary words across languages](https://what3words.com/news/blog/how-what3words-supports-natural-variants-across-languages-using-secondary-words)\n- [Blog: Understanding the what3words regex](https://what3words.com/news/general/understanding-the-what3words-regex-a-human-friendly-guide)\n", "version": "1.0.0", "contact": { "name": "what3words Developer Support", "url": "https://developer.what3words.com", "email": "support@what3words.com" } }, "servers": [ { "url": "https://api.what3words.com/v3", "description": "what3words API v3" } ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ { "name": "what3words API", "description": "API endpoints for interacting with the what3words addressing system.", "externalDocs": { "description": "API Documentation", "url": "https://developer.what3words.com/public-api/docs#overview" } } ], "paths": { "/convert-to-3wa": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "Convert to what3words address", "description": "This function will convert a latitude and longitude to a what3words address, in the language of your choice. It also returns country, the bounds of the grid square, a nearby place (such as a local town) and a link to our map site.", "operationId": "convertTo3wa", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "coordinates", "in": "query", "description": "Coordinates as a comma separated string of latitude and longitude", "required": true, "schema": { "type": "string", "examples": [ "51.521251,-0.203586" ] } }, { "name": "language", "in": "query", "description": "A supported what3words language code from `/available-languages`. You can pass base language codes (for example `fr`) or script-specific codes where available (for example `mn_la`, `zh_tr`, `oo_la`). Defaults to `en` (English) if not specified.", "required": false, "schema": { "type": "string", "default": "en", "examples": [ "fr" ] } }, { "name": "format", "in": "query", "description": "Return data format type; can be either `json` (the default) or `geojson`", "required": false, "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json" } }, { "name": "locale", "in": "query", "description": "Optional locale/script-specific code. Can be passed on its own. If provided with `language`, both values must be identical strings (for example `language=mn_la&locale=mn_la`).", "required": false, "schema": { "type": "string", "examples": [ "mn_la" ] } } ], "responses": { "200": { "description": "Successful conversion to what3words address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertTo3waResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "BadLanguage": { "summary": "Bad language format", "value": { "error": { "code": "BadLanguage", "message": "language must be a supported what3words language code, such as 'en', 'fr' or 'mn_la'" } } }, "BadCoordinates": { "summary": "Bad coordinates format", "value": { "error": { "code": "BadCoordinates", "message": "failed to parse one of the coordinates as a valid decimal number" } } }, "BadFormat": { "summary": "Bad format value", "value": { "error": { "code": "BadFormat", "message": "Format must be one of json,geojson" } } }, "BadLanguageLocaleMismatch": { "summary": "Language/locale mismatch", "value": { "error": { "code": "BadLanguage", "message": "language and locale must not be different" } } }, "DuplicateParameter": { "summary": "Duplicate parameter", "value": { "error": { "code": "DuplicateParameter", "message": "Duplicate parameter 'coordinates'. Please only pass in one of each parameter." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } }, "/convert-to-coordinates": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "Convert to coordinates", "description": "This function converts a what3words address to a latitude and longitude. It also returns country, the bounds of the grid square, a nearest place (such as a local town) and a link to our map site.", "operationId": "convertToCoordinates", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "words", "in": "query", "description": "A what3words address. Input parsing is case-insensitive, accepts an optional leading `///`, and accepts supported dot-like delimiters (. ｡ 。 ･ ・ ︒ ។ ։ ။ ۔ ። ।).", "required": true, "schema": { "type": "string", "examples": [ "filled.count.soap" ] } }, { "name": "format", "in": "query", "description": "Return data format type; can be either `json` (the default) or `geojson`", "required": false, "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json" } } ], "responses": { "200": { "description": "Successful conversion to coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertToCoordinatesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "MissingWords": { "summary": "Missing words parameter", "value": { "error": { "code": "MissingWords", "message": "words must be specified" } } }, "BadWords": { "summary": "Bad words format", "value": { "error": { "code": "BadWords", "message": "words must be a valid 3 word address, such as filled.count.soap or ///filled.count.soap" } } }, "BadFormat": { "summary": "Bad format value", "value": { "error": { "code": "BadFormat", "message": "Format must be one of json,geojson" } } }, "DuplicateParameter": { "summary": "Duplicate parameter", "value": { "error": { "code": "DuplicateParameter", "message": "Duplicate parameter 'words'. Please only pass in one of each parameter." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } }, "/autosuggest": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "AutoSuggest", "description": "AutoSuggest can take a slightly incorrect what3words address and suggest a list of valid what3words addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritize results that are near the user.", "operationId": "autosuggest", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "input", "in": "query", "description": "The full or partial what3words address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word. Input parsing is case-insensitive, accepts an optional leading `///`, and accepts supported dot-like delimiters (. ｡ 。 ･ ・ ︒ ។ ։ ။ ۔ ። ।).", "required": true, "schema": { "type": "string", "examples": [ "filled.count.s" ] } }, { "name": "focus", "in": "query", "description": "This is a location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus. For convenience, longitude is allowed to wrap around the 180 line, so 361 is equivalent to 1.", "required": false, "schema": { "type": "string", "examples": [ "51.521251,-0.203586" ] } }, { "name": "n-focus-results", "in": "query", "description": "Controls how many top suggestions are strongly biased towards the `focus` coordinate. Defaults to `n-results` when omitted. Non-numeric values return `BadNFocusResults`.", "required": false, "schema": { "type": "string", "default": "3", "maximum": 100, "examples": [ "5" ] } }, { "name": "clip-to-country", "in": "query", "description": "Restricts results to the specified country or countries, specified as comma-separated ISO 3166-1 alpha-2 country codes (for example `GB,US`). Parsing is case-insensitive, though uppercase is recommended.", "required": false, "schema": { "type": "string", "examples": [ "GB,US" ] } }, { "name": "clip-to-circle", "in": "query", "description": "Restricts results to a circle, specified by `latitude,longitude,kilometres`. For example, `51.4243877,-0.3474524,10` constrains results to those within 10 km of the point 51.4243877,-0.3474524.", "required": false, "schema": { "type": "string", "examples": [ "51.4243877,-0.3474524,10" ] } }, { "name": "clip-to-bounding-box", "in": "query", "description": "Restricts results to a bounding box, specified by `southwest latitude,southwest longitude,northeast latitude,northeast longitude`. Latitudes and longitudes should be specified in order of increasing size. Longitude is allowed to wrap, so that you can specify bounding boxes which cross the ante-meridian, e.g., `-4,178.2,22,195.4`", "required": false, "schema": { "type": "string", "examples": [ "51.515900,-0.212517,51.527649,-0.191746" ] } }, { "name": "clip-to-polygon", "in": "query", "description": "Restricts results to a polygon, specified by a comma-separated list of `lat,lng` pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs.", "required": false, "schema": { "type": "string", "examples": [ "51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343" ] } }, { "name": "language", "in": "query", "description": "For text input, adds a preferred language or locale to the set Autosuggest considers. Exact whole-word matches in the input can also add languages or locales. If omitted for text input, English is added as the default backstop. For voice input (`input-type` != `text`), this must be provided. Use a supported what3words code from `/available-languages`, including locale/script-specific codes where available (for example `mn_la`, `zh_tr`, `oo_la`).", "required": false, "schema": { "type": "string", "default": "en" } }, { "name": "locale", "in": "query", "description": "Optional locale/script-specific code. Can be passed on its own. If provided with `language`, both values must be identical strings (for example `language=mn_la&locale=mn_la`).", "required": false, "schema": { "type": "string", "examples": [ "mn_la" ] } }, { "name": "input-type", "in": "query", "description": "For power users, used to specify voice input mode. Can be `text` (default), `vocon-hybrid`, `nmdp-asr`, `generic-voice`, `speechmatics`, or `vin-big-data`. Voice modes require `language`. If `input` is not in the expected format for a selected voice mode, the API may return `BadInput`.", "required": false, "schema": { "type": "string", "enum": [ "text", "vocon-hybrid", "nmdp-asr", "generic-voice", "speechmatics", "vin-big-data" ], "default": "text" } }, { "name": "n-results", "in": "query", "description": "The number of AutoSuggest results to return. Non-numeric values return `BadNResults`. Values greater than 100 are truncated to 100. Values less than or equal to 0 return an empty suggestions list. The default is 3.", "required": false, "schema": { "type": "integer", "default": 3, "maximum": 100 } }, { "name": "prefer-land", "in": "query", "description": "Makes AutoSuggest prefer results on land to those in the sea. This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "format", "in": "query", "description": "Return data format type; can be either `json` (the default) or `geojson`", "required": false, "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json" } } ], "responses": { "200": { "description": "Successful autosuggest results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutosuggestResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "MissingInput": { "summary": "Missing input parameter", "value": { "error": { "code": "MissingInput", "message": "input must be specified" } } }, "BadFocus": { "summary": "Bad focus format", "value": { "error": { "code": "BadFocus", "message": "focus must be a lat,lng" } } }, "BadClipToCountry": { "summary": "Bad clip-to-country format", "value": { "error": { "code": "BadClipToCountry", "message": "Countries are specified as a comma separated list of uppercase ISO 3166-1 alpha-2 country codes, such as US,CA" } } }, "BadClipToBoundingBox": { "summary": "Bad clip-to-bounding-box format", "value": { "error": { "code": "BadClipToBoundingBox", "message": "Must be four lat,lng,lat,lng coordinates such as 50,-2,53.12,2.34" } } }, "BadClipToCircle": { "summary": "Bad clip-to-circle format", "value": { "error": { "code": "BadClipToCircle", "message": "clip-to-circle needs to be lat,lng,km. Example: 51.453,0.344,112" } } }, "BadClipToPolygon": { "summary": "Bad clip-to-polygon format", "value": { "error": { "code": "BadClipToPolygon", "message": "Failed to parse one of the coordinates as a valid decimal number" } } }, "MissingLanguage": { "summary": "Missing language parameter", "value": { "error": { "code": "MissingLanguage", "message": "for voice input. language must be specified" } } }, "BadLanguage": { "summary": "Bad language format", "value": { "error": { "code": "BadLanguage", "message": "language must be a supported what3words language code, such as 'en', 'fr' or 'mn_la'" } } }, "BadInputType": { "value": { "error": { "code": "BadInputType", "message": "prefer-land must be one of true or false" } } }, "BadLanguageLocaleMismatch": { "summary": "Language/locale mismatch", "value": { "error": { "code": "BadLanguage", "message": "language and locale must not be different" } } }, "BadNResults": { "summary": "Bad n-results format", "value": { "error": { "code": "BadNResults", "message": "n-results must be a valid integer" } } }, "BadNFocusResults": { "summary": "Bad n-focus-results format", "value": { "error": { "code": "BadNFocusResults", "message": "n-focus-results must be a valid integer" } } }, "BadInput": { "summary": "Bad voice input format", "value": { "error": { "code": "BadInput", "message": "Invalid autosuggest input" } } }, "DuplicateParameter": { "summary": "Duplicate parameter", "value": { "error": { "code": "DuplicateParameter", "message": "Duplicate parameter 'input'. Please only pass in one of each parameter." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } }, "/autosuggest-with-coordinates": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "AutoSuggest with Coordinates", "description": "Similar to the AutoSuggest endpoint, but returns coordinates in the response. This endpoint requires special permissions.", "operationId": "autosuggestWithCoordinates", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "input", "in": "query", "description": "The full or partial what3words address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word. Input parsing is case-insensitive, accepts an optional leading `///`, and accepts supported dot-like delimiters (. ｡ 。 ･ ・ ︒ ។ ։ ။ ۔ ። ।).", "required": true, "schema": { "type": "string", "examples": [ "filled.count.s" ] } }, { "name": "focus", "in": "query", "description": "This is a location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus. For convenience, longitude is allowed to wrap around the 180 line, so 361 is equivalent to 1.", "required": false, "schema": { "type": "string", "examples": [ "51.521251,-0.203586" ] } }, { "name": "n-focus-results", "in": "query", "description": "Controls how many top suggestions are strongly biased towards the `focus` coordinate. Defaults to `n-results` when omitted. Non-numeric values return `BadNFocusResults`.", "required": false, "schema": { "type": "string", "default": "3", "maximum": 100, "examples": [ "5" ] } }, { "name": "clip-to-country", "in": "query", "description": "Restricts results to the specified country or countries, specified as comma-separated ISO 3166-1 alpha-2 country codes (for example `GB,US`). Parsing is case-insensitive, though uppercase is recommended.", "required": false, "schema": { "type": "string", "examples": [ "GB,US" ] } }, { "name": "clip-to-circle", "in": "query", "description": "Restricts results to a circle, specified by `latitude,longitude,kilometres`. For example, `51.4243877,-0.3474524,10` constrains results to those within 10 km of the point 51.4243877,-0.3474524.", "required": false, "schema": { "type": "string", "examples": [ "51.4243877,-0.3474524,10" ] } }, { "name": "clip-to-bounding-box", "in": "query", "description": "Restricts results to a bounding box, specified by `southwest latitude,southwest longitude,northeast latitude,northeast longitude`. Latitudes and longitudes should be specified in order of increasing size. Longitude is allowed to wrap, so that you can specify bounding boxes which cross the ante-meridian, e.g., `-4,178.2,22,195.4`", "required": false, "schema": { "type": "string", "examples": [ "51.515900,-0.212517,51.527649,-0.191746" ] } }, { "name": "clip-to-polygon", "in": "query", "description": "Restricts results to a polygon, specified by a comma-separated list of `lat,lng` pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs.", "required": false, "schema": { "type": "string", "examples": [ "51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343" ] } }, { "name": "language", "in": "query", "description": "For text input, adds a preferred language or locale to the set Autosuggest considers. Exact whole-word matches in the input can also add languages or locales. If omitted for text input, English is added as the default backstop. For voice input (`input-type` != `text`), this must be provided. Use a supported what3words code from `/available-languages`, including locale/script-specific codes where available (for example `mn_la`, `zh_tr`, `oo_la`).", "required": false, "schema": { "type": "string", "default": "en" } }, { "name": "locale", "in": "query", "description": "Optional locale/script-specific code. Can be passed on its own. If provided with `language`, both values must be identical strings (for example `language=mn_la&locale=mn_la`).", "required": false, "schema": { "type": "string", "examples": [ "mn_la" ] } }, { "name": "input-type", "in": "query", "description": "For power users, used to specify voice input mode. Can be `text` (default), `vocon-hybrid`, `nmdp-asr`, `generic-voice`, `speechmatics`, or `vin-big-data`. Voice modes require `language`. If `input` is not in the expected format for a selected voice mode, the API may return `BadInput`.", "required": false, "schema": { "type": "string", "enum": [ "text", "vocon-hybrid", "nmdp-asr", "generic-voice", "speechmatics", "vin-big-data" ], "default": "text" } }, { "name": "n-results", "in": "query", "description": "The number of AutoSuggest results to return. Non-numeric values return `BadNResults`. Values greater than 100 are truncated to 100. Values less than or equal to 0 return an empty suggestions list. The default is 3.", "required": false, "schema": { "type": "integer", "default": 3, "maximum": 100 } }, { "name": "prefer-land", "in": "query", "description": "Makes AutoSuggest prefer results on land to those in the sea. This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "format", "in": "query", "description": "Return data format type; can be either `json` (the default) or `geojson`", "required": false, "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json" } } ], "responses": { "200": { "description": "Successful autosuggest results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutosuggestWithCoordinatesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "MissingInput": { "summary": "Missing input parameter", "value": { "error": { "code": "MissingInput", "message": "input must be specified" } } }, "BadFocus": { "summary": "Bad focus format", "value": { "error": { "code": "BadFocus", "message": "focus must be a lat,lng" } } }, "BadClipToCountry": { "summary": "Bad clip-to-country format", "value": { "error": { "code": "BadClipToCountry", "message": "Countries are specified as a comma separated list of uppercase ISO 3166-1 alpha-2 country codes, such as US,CA" } } }, "BadClipToBoundingBox": { "summary": "Bad clip-to-bounding-box format", "value": { "error": { "code": "BadClipToBoundingBox", "message": "Must be four lat,lng,lat,lng coordinates such as 50,-2,53.12,2.34" } } }, "BadClipToCircle": { "summary": "Bad clip-to-circle format", "value": { "error": { "code": "BadClipToCircle", "message": "clip-to-circle needs to be lat,lng,km. Example: 51.453,0.344,112" } } }, "BadClipToPolygon": { "summary": "Bad clip-to-polygon format", "value": { "error": { "code": "BadClipToPolygon", "message": "Failed to parse one of the coordinates as a valid decimal number" } } }, "MissingLanguage": { "summary": "Missing language parameter", "value": { "error": { "code": "MissingLanguage", "message": "for voice input. language must be specified" } } }, "BadLanguage": { "summary": "Bad language format", "value": { "error": { "code": "BadLanguage", "message": "language must be a supported what3words language code, such as 'en', 'fr' or 'mn_la'" } } }, "BadInputType": { "value": { "error": { "code": "BadInputType", "message": "prefer-land must be one of true or false" } } }, "BadLanguageLocaleMismatch": { "summary": "Language/locale mismatch", "value": { "error": { "code": "BadLanguage", "message": "language and locale must not be different" } } }, "BadNResults": { "summary": "Bad n-results format", "value": { "error": { "code": "BadNResults", "message": "n-results must be a valid integer" } } }, "BadNFocusResults": { "summary": "Bad n-focus-results format", "value": { "error": { "code": "BadNFocusResults", "message": "n-focus-results must be a valid integer" } } }, "BadInput": { "summary": "Bad voice input format", "value": { "error": { "code": "BadInput", "message": "Invalid autosuggest input" } } }, "DuplicateParameter": { "summary": "Duplicate parameter", "value": { "error": { "code": "DuplicateParameter", "message": "Duplicate parameter 'input'. Please only pass in one of each parameter." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "InvalidKeyNoPermissions": { "summary": "Authentication failed - No permissions", "value": { "error": { "code": "InvalidKey", "message": "Auth failed; /v3/autosuggest-with-coordinates. Contact support@what3words.com or your account manager to enable your account" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } }, "/grid-section": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "Grid section", "description": "Returns a section of the 3m x 3m what3words grid for a bounding box. The bounding box is specified by lat,lng,lat,lng as south,west,north,east. You can request the grid in GeoJSON format, making it very simple to display on a map.", "operationId": "gridSection", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "bounding-box", "in": "query", "description": "Bounding box, as a `lat,lng,lat,lng`, for which the grid should be returned. The requested box must not exceed `4km` from corner to corner, or a `BadBoundingBoxTooBig` error will be returned. Latitudes must be `>= -90` and `<= 90`, but longitudes are allowed to wrap around 180. To specify a bounding-box that crosses the anti-meridian, use longitude greater than 180. e.g.: `bounding-box=50.0,179.995,50.01,180.0005`", "required": true, "schema": { "type": "string", "examples": [ "52.207988,0.116126,52.208867,0.117540" ] } }, { "name": "format", "in": "query", "description": "Return data format type; can be either `json` (the default) or `geojson`", "required": false, "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json" } } ], "responses": { "200": { "description": "Successful grid section retrieval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GridSectionResponse" } }, "application/geo+json": { "schema": { "$ref": "#/components/schemas/GridSectionGeoJsonResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorResponse" } }, "examples": { "BadBoundingBox": { "summary": "Bad bounding box format", "value": { "error": { "code": "BadBoundingBox", "message": "bounding-box must be specified as south_lat,west_lng,north_lat,east_lng" } } }, "BadBoundingBoxTooBig": { "summary": "Bounding box too large", "value": { "error": { "code": "BadBoundingBoxTooBig", "message": "Bounding box too large (exceeds 4km from corner to corner)" } } }, "BadFormat": { "summary": "Bad format value", "value": { "error": { "code": "BadFormat", "message": "Format must be one of json,geojson" } } }, "DuplicateParameter": { "summary": "Duplicate parameter", "value": { "error": { "code": "DuplicateParameter", "message": "Duplicate parameter 'bounding-box'. Please only pass in one of each parameter." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } }, "/available-languages": { "get": { "security": [ { "ApiKeyAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ "what3words API" ], "summary": "Available languages", "description": "Retrieves all available what3words address languages and locale/script variants, including language code, English name and native name. Use top-level `code` values as base `language` codes, and use nested `locales[].code` values where explicit locale/script selection is needed (for example `en`, `mn`, `mn_la`, `zh_tr`, `oo_cy`).", "operationId": "availableLanguages", "parameters": [ { "name": "key", "in": "query", "description": "A valid API key. Provide it as query parameter `key`; `X-Api-Key` header is also supported.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of available languages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableLanguagesResponse" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidKey": { "summary": "Authentication failed", "value": { "error": { "code": "InvalidKey", "message": "Authentication failed; invalid API key" } } }, "MissingKey": { "summary": "Authentication failed - missing key", "value": { "error": { "code": "MissingKey", "message": "Authentication failed; missing required API key parameter or header" } } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "query", "name": "key", "description": "API key for authentication. Provide it as query parameter `key`; `X-Api-Key` header is also supported." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key for authentication. Provide it as query parameter `key`; `X-Api-Key` header is also supported." } }, "schemas": { "Coordinates": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "description": "Latitude", "examples": [ 51.520847 ] }, "lng": { "type": "number", "format": "double", "description": "Longitude", "examples": [ -0.195521 ] } } }, "Square": { "type": "object", "properties": { "southwest": { "$ref": "#/components/schemas/Coordinates" }, "northeast": { "$ref": "#/components/schemas/Coordinates" } } }, "ConvertTo3waResponse": { "type": "object", "properties": { "country": { "type": "string", "description": "The country in which the what3words address is located, as an ISO 3166-1 alpha-2 country code", "examples": [ "GB" ] }, "square": { "$ref": "#/components/schemas/Square" }, "nearestPlace": { "type": "string", "description": "The nearest place to the what3words address", "examples": [ "Bayswater, London" ] }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "words": { "type": "string", "description": "The what3words address", "examples": [ "filled.count.soap" ] }, "language": { "type": "string", "description": "The language of the what3words address", "examples": [ "en" ] }, "locale": { "type": "string", "description": "The locale of the what3words address, if returned", "examples": [ "mn_la" ] }, "map": { "type": "string", "description": "URL to view the what3words address on the what3words map", "examples": [ "https://w3w.co/filled.count.soap" ] } } }, "ConvertToCoordinatesResponse": { "type": "object", "properties": { "country": { "type": "string", "description": "The country in which the what3words address is located, as an ISO 3166-1 alpha-2 country code", "examples": [ "GB" ] }, "square": { "$ref": "#/components/schemas/Square" }, "nearestPlace": { "type": "string", "description": "The nearest place to the what3words address", "examples": [ "Bayswater, London" ] }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "words": { "type": "string", "description": "The what3words address", "examples": [ "filled.count.soap" ] }, "language": { "type": "string", "description": "The language of the what3words address", "examples": [ "en" ] }, "locale": { "type": "string", "description": "The locale of the what3words address, if returned", "examples": [ "mn_la" ] }, "map": { "type": "string", "description": "URL to view the what3words address on the what3words map", "examples": [ "https://w3w.co/filled.count.soap" ] } } }, "Suggestion": { "type": "object", "properties": { "words": { "type": "string", "description": "The suggested what3words address", "examples": [ "filled.count.also" ] }, "country": { "type": "string", "description": "The country in which the what3words address is located, as an ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "square": { "$ref": "#/components/schemas/Square" }, "nearestPlace": { "type": "string", "description": "The nearest place to the what3words address", "examples": [ "Chillum, Maryland" ] }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "language": { "type": "string", "description": "The language of the what3words address", "examples": [ "en" ] }, "locale": { "type": "string", "description": "The locale of the what3words address, if returned", "examples": [ "mn_la" ] }, "rank": { "type": "integer", "description": "The relative ranking of this suggestion", "examples": [ 1 ] }, "distanceToFocusKm": { "type": "number", "format": "double", "description": "The distance in kilometers from the focus point to this suggestion's coordinates", "examples": [ 1.2 ] } } }, "AutosuggestResponse": { "type": "object", "properties": { "suggestions": { "type": "array", "description": "List of suggested what3words addresses", "items": { "$ref": "#/components/schemas/AutosuggestSuggestion" } } } }, "GridSectionResponse": { "type": "object", "properties": { "lines": { "type": "array", "description": "Array of line objects that make up the grid", "items": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/Coordinates" }, "end": { "$ref": "#/components/schemas/Coordinates" } } } } } }, "GridSectionGeoJsonResponse": { "type": "object", "description": "GeoJSON representation of the grid section" }, "Locale": { "type": "object", "properties": { "code": { "type": "string", "description": "The locale code", "examples": [ "mn_cy" ] }, "name": { "type": "string", "description": "The name of the locale", "examples": [ "Mongolian (Cyrillic)" ] }, "nativeName": { "type": "string", "description": "The native name of the locale", "examples": [ "Монгол хэл (Криллээр)" ] } } }, "Language": { "type": "object", "properties": { "code": { "type": "string", "description": "The what3words language code for the language or language family (for example `en`, `mn`, `oo`).", "examples": [ "de" ] }, "name": { "type": "string", "description": "The English name of the language", "examples": [ "German" ] }, "nativeName": { "type": "string", "description": "The name of the language in that language", "examples": [ "Deutsch" ] }, "locales": { "type": "array", "description": "List of available locales for this language, if applicable", "items": { "$ref": "#/components/schemas/Locale" } } } }, "AvailableLanguagesResponse": { "type": "object", "properties": { "languages": { "type": "array", "description": "List of available languages", "items": { "$ref": "#/components/schemas/Language" } } } }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code that can be used programmatically", "examples": [ "BadWords" ], "enum": [ "MissingWords", "BadWords", "BadFormat", "BadCoordinates", "BadBoundingBox", "BadBoundingBoxTooBig", "BadFocus", "BadClipToCountry", "BadClipToBoundingBox", "BadClipToCircle", "BadClipToPolygon", "MissingLanguage", "BadLanguage", "InvalidKey", "InvalidKeyNoPermissions", "BadInputType", "MissingInput", "MissingKey", "DuplicateParameter", "BadNResults", "BadNFocusResults", "BadInput" ] }, "message": { "type": "string", "description": "A helpful message explaining what went wrong", "examples": [ "Invalid or non-existent 3 word address: 'no.address.here'" ] } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "AutosuggestSuggestion": { "type": "object", "properties": { "words": { "type": "string", "description": "The suggested what3words address", "examples": [ "filled.count.also" ] }, "country": { "type": "string", "description": "The country in which the what3words address is located, as an ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "nearestPlace": { "type": "string", "description": "The nearest place to the what3words address", "examples": [ "Chillum, Maryland" ] }, "language": { "type": "string", "description": "The language of the what3words address", "examples": [ "en" ] }, "locale": { "type": "string", "description": "The locale of the what3words address, if applicable", "examples": [ "mn_la" ] }, "rank": { "type": "integer", "description": "The relative ranking of this suggestion", "examples": [ 1 ] }, "distanceToFocusKm": { "type": "number", "format": "double", "description": "The distance in kilometers from the focus point to this suggestion's coordinates", "examples": [ 1.2 ] } } }, "AutosuggestWithCoordinatesSuggestion": { "type": "object", "properties": { "words": { "type": "string", "description": "The suggested what3words address", "examples": [ "filled.count.also" ] }, "country": { "type": "string", "description": "The country in which the what3words address is located, as an ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "square": { "$ref": "#/components/schemas/Square" }, "nearestPlace": { "type": "string", "description": "The nearest place to the what3words address", "examples": [ "Chillum, Maryland" ] }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "language": { "type": "string", "description": "The language of the what3words address", "examples": [ "en" ] }, "locale": { "type": "string", "description": "The locale of the what3words address, if returned", "examples": [ "mn_la" ] }, "rank": { "type": "integer", "description": "The relative ranking of this suggestion", "examples": [ 1 ] }, "distanceToFocusKm": { "type": "number", "format": "double", "description": "The distance in kilometers from the focus point to this suggestion's coordinates", "examples": [ 1.2 ] }, "map": { "type": "string", "description": "URL to view the what3words address on the what3words map", "examples": [ "https://w3w.co/filled.count.also" ] } } }, "AutosuggestWithCoordinatesResponse": { "type": "object", "properties": { "suggestions": { "type": "array", "description": "List of suggested what3words addresses including coordinates", "items": { "$ref": "#/components/schemas/AutosuggestWithCoordinatesSuggestion" } } } } } } }