{"openapi":"3.0.2","info":{"title":"what3words API","description":"The what3words API is a fast and simple interface that allows you to convert 3 word addresses to coordinates and vice versa.\\\nThis flavor of W3W is hosted on HERE Delivery Platform.","contact":{},"version":"v3"},"servers":[{"url":"https://what3words.search.hereapi.com/v3"},{"url":"https://what3words-sit-eu-north-1.gw.stratus-ls-rd.ops.in.hereapi.com/v3"}],"security":[{"ServiceToken":[]},{"AccessToken":[]}],"tags":[{"name":"Convert to 3 words address","description":"Convert a latitude and longitude to a 3 word address."},{"name":"Convert to coordinates","description":"Converts a 3 word address to a latitude and longitude."},{"name":"AutoSuggest","description":"Take a slightly incorrect 3 word address and suggest a list of valid 3 word addresses."},{"name":"Grid section","description":"Returns a section of the 3m x 3m what3words grid for a bounding box."},{"name":"Available languages","description":"Retrieves a list all available 3 word address languages."}],"paths":{"/convert-to-3wa":{"get":{"tags":["Convert to 3 words address"],"summary":"Convert a latitude and longitude to a 3 word address.","description":"Convert a latitude and longitude to a 3 word address. It also returns country, the bounds of the grid square, a nearby place (such as a local town) and a link to W3W map site.","operationId":"convertto3wa","parameters":[{"$ref":"#/components/parameters/Coordinates"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Format"},{"$ref":"#/components/parameters/Locale"}],"responses":{"200":{"$ref":"#/components/responses/ConvertResponse"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error400"},"500":{"$ref":"#/components/responses/Error500"}}}},"/convert-to-coordinates":{"get":{"tags":["Convert to coordinates"],"summary":"Convert a latitude and longitude to a 3 word address.","description":"Converts a 3 word 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 W3W map site.","operationId":"converttocoordinates","parameters":[{"$ref":"#/components/parameters/Words"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Format"},{"$ref":"#/components/parameters/Locale"}],"responses":{"200":{"$ref":"#/components/responses/ConvertResponse"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error400"},"500":{"$ref":"#/components/responses/Error500"}}}},"/autosuggest":{"get":{"tags":["AutoSuggest"],"summary":"Suggest a list of valid 3 word addresses.","description":"AutoSuggest can take a slightly incorrect 3 word address and suggest a list of valid 3 word addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritise results that are near the user.\nIt provides corrections for the following types of input error:\n* Typing errors\n* Spelling errors\n* Misremembered words (e.g. singular vs. plural)\n* Words in the wrong order\n","operationId":"autosuggest","parameters":[{"$ref":"#/components/parameters/Input"},{"$ref":"#/components/parameters/Focus"},{"$ref":"#/components/parameters/Clip-to-country"},{"$ref":"#/components/parameters/Clip-to-bounding-box"},{"$ref":"#/components/parameters/Clip-to-circle"},{"$ref":"#/components/parameters/Clip-to-polygon"},{"$ref":"#/components/parameters/Input-type"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Prefer-land"},{"$ref":"#/components/parameters/Locale"}],"responses":{"200":{"$ref":"#/components/responses/AutoSuggestResponse"}}}},"/grid-section":{"get":{"tags":["Grid section"],"summary":"Returns a section of the 3m x 3m what3words grid for a bounding box.","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":[{"$ref":"#/components/parameters/Bounding-box"},{"$ref":"#/components/parameters/Format"}],"responses":{"200":{"$ref":"#/components/responses/GridSectionResponse"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error400"},"500":{"$ref":"#/components/responses/Error500"}}}},"/available-languages":{"get":{"tags":["Available languages"],"summary":"Retrieves a list all available 3 word address languages.","description":"Retrieves a list all available 3 word address languages, including the ISO 3166-1 alpha-2 2 letter code, english name and native name..","operationId":"available-languages","responses":{"200":{"$ref":"#/components/responses/AvailableLanguagesResponse"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error400"},"500":{"$ref":"#/components/responses/Error500"}}}}},"components":{"securitySchemes":{"ServiceToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nFor more information on how to get a bearer token, see the [Identity & Access Management Guide](https://developer.here.com/documentation/identity-access-management/dev_guide/index.html).\n"},"AccessToken":{"type":"apiKey","in":"query","name":"apiKey","description":"A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity & Access Management Guide](https://developer.here.com/documentation/identity-access-management/dev_guide/index.html).\n"}},"parameters":{"Words":{"name":"words","in":"query","description":"A 3 word address as a string. It must be three words separated with dots or a japanese middle dot character (・). Words separated by spaces will be rejected. Optionally, the 3 word address can be prefixed with /// (which would be encoded as %2F%2F%2F).","required":true,"schema":{"type":"string"},"example":"filled.count.soap"},"Coordinates":{"name":"coordinates","in":"query","description":"Coordinates as a comma separated string of latitude and longitude.","required":true,"schema":{"type":"string"},"example":"51.521251,-0.203586"},"Bounding-box":{"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. EG:bounding-box=50.0,179.995,50.01,180.0005.","required":true,"schema":{"type":"string"}},"Input":{"name":"input","in":"query","description":"The full or partial 3 word address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word.","required":true,"schema":{"type":"string"}},"Focus":{"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"}},"Clip-to-country":{"name":"clip-to-country","in":"query","description":"Restricts AutoSuggest to only return results inside the countries specified by comma-separated list of uppercase ISO 3166-1 alpha-2 country codes (for example, to restrict to Belgium and the UK, use clip-to-country=GB,BE). Clip-to-country will also accept lowercase country codes. Entries must be two a-z letters. WARNING:If the two-letter code does not correspond to a country, there is no error:API simply returns no results.","required":false,"schema":{"type":"string"}},"Clip-to-bounding-box":{"name":"clip-to-bounding-box","in":"query","description":"Restrict AutoSuggest results to a bounding box, specified by coordinates.south_lat,west_lng,north_lat,east_lng, where:south_lat less than or equal to north_latwest_lng less than or equal to east_lngIn other words, latitudes and longitudes should be specified order of increasing size. Lng is allowed to wrap, so that you can specify bounding boxes which cross the ante-meridian:-4,178.2,22,195.4.","required":false,"schema":{"type":"string"}},"Clip-to-circle":{"name":"clip-to-circle","in":"query","description":"Restrict AutoSuggest results to a circle, specified by lat,lng,kilometres, where kilometres in the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.","required":false,"schema":{"type":"string"}},"Clip-to-polygon":{"name":"clip-to-polygon","in":"query","description":"Restrict AutoSuggest 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"}},"Input-type":{"name":"input-type","in":"query","description":"For power users, used to specify voice input mode. Can be text (default),vocon-hybrid, nmdp-asr or generic-voice. see speech recognition.for more details.","required":false,"schema":{"type":"string","default":"text"}},"Prefer-land":{"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","enum":[true,false],"default":true}},"Language":{"name":"language","in":"query","description":"A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en (english).","required":false,"schema":{"type":"string","default":"en"}},"Format":{"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"}},"Locale":{"name":"locale","in":"query","description":"Locale to specify a variant of a language.","required":false,"schema":{"type":"string","enum":["oo_cy","oo_la","kk_cy","kk_la","mn_cy","mn_la","zh_tr","zh_si"]}}},"responses":{"ConvertResponse":{"description":"The conversion result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionResult"},"example":{"country":"GB","square":{"southwest":{"lng":-0.195543,"lat":51.520833},"northeast":{"lng":-0.195499,"lat":51.52086}},"nearestPlace":"Bayswater, London","coordinates":{"lng":-0.195521,"lat":51.520847},"words":"filled.count.soap","language":"en","map":"https://w3w.co/filled.count.soap"}},"application/geo+json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"},"example":{"features":[{"bbox":[-0.195543,51.520833,-0.195499,51.52086],"geometry":{"coordinates":[-0.195521,51.520847],"type":"Point"},"type":"Feature","properties":{"country":"GB","nearestPlace":"Bayswater, London","words":"filled.count.soap","language":"en","map":"https://w3w.co/filled.count.soap"}}],"type":"FeatureCollection"}}}},"AutoSuggestResponse":{"description":"The AutoSuggest result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoSuggestResult"},"example":{"suggestions":[{"country":"BE","nearestPlace":"Brussels, Brussels Capital","words":"film.crunchy.spirits","distanceToFocusKm":1,"rank":1,"language":"en"},{"country":"ES","nearestPlace":"Caldes de Montbui, Catalonia","words":"film.crunchy.spirit","distanceToFocusKm":1039,"rank":2,"language":"en"},{"country":"NL","nearestPlace":"Weert, Limburg","words":"firm.crunchy.spires","distanceToFocusKm":105,"rank":3,"language":"en"}]}}}},"GridSectionResponse":{"description":"The result object of Grid Section","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridSectionResult"},"example":{"lines":[{"start":{"lng":0.116126,"lat":52.208009918068136},"end":{"lng":0.11754,"lat":52.208009918068136}},{"start":{"lng":0.116126,"lat":52.20803686934023},"end":{"lng":0.11754,"lat":52.20803686934023}}]}},"application/geo+json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"},"example":{"features":[{"geometry":{"coordinates":[[[0.116126,52.208009918068136],[0.11754,52.208009918068136]],[[0.116126,52.20803686934023],[0.11754,52.20803686934023]]],"type":"MultiLineString"},"type":"Feature","properties":{}}],"type":"FeatureCollection"}}}},"AvailableLanguagesResponse":{"description":"List all available languages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguagesResult"}}}},"Error400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"URL not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"ConversionResult":{"type":"object","description":"A conversion result object in JSON format.","properties":{"country":{"description":"The unique country code.","type":"string"},"square":{"type":"object","description":"The cooridnates of the bounds of the grid square.","properties":{"southwest":{"allOf":[{"$ref":"#/components/schemas/CoordinateObject"}]},"northeast":{"allOf":[{"$ref":"#/components/schemas/CoordinateObject"}]}}},"nearestPlace":{"description":"Name of nearby places.","type":"string"},"coordinates":{"description":"Coordinates of nearby places.","type":"object","properties":{"lng":{"type":"number","format":"double"},"lat":{"type":"number","format":"double"}}},"words":{"description":"The what three words.","type":"string"},"language":{"description":"The selected language.","type":"string"},"map":{"description":"Link to the w3w map site.","type":"string"}}},"AutoSuggestResult":{"type":"object","description":"An AutoSuggest result object","properties":{"suggestions":{"type":"array","items":{"type":"object","description":"An AutoSuggest object","properties":{"country":{"type":"string"},"nearestPlace":{"type":"string"},"words":{"type":"string"},"distanceToFocusKm":{"type":"string"},"rank":{"type":"string"},"language":{"type":"string"}}}}}},"GridSectionResult":{"type":"object","description":"The section of the 3m x 3m what3words grid for a bounding box","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/CoordinateObject"},"end":{"$ref":"#/components/schemas/CoordinateObject"}}}}}},"LanguagesResult":{"type":"object","description":"Object holds all available 3 word address languages","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"nativeName":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}}}}}},"CoordinateObject":{"type":"object","description":"The basic cooridnate object which holds lat and long","properties":{"lng":{"type":"number","format":"double"},"lat":{"type":"number","format":"double"}}},"GeoJsonObject":{"description":"GeoJSon object The coordinate reference system for all GeoJSON coordinates is a geographic coordinate reference system, using the World Geodetic System 1984 (WGS 84) datum, with longitude and latitude units of decimal degrees. This is equivalent to the coordinate reference system identified by the Open Geospatial Consortium (OGC) URN An OPTIONAL third-position element SHALL be the height in meters above or below the WGS 84 reference ellipsoid. In the absence of elevation values, applications sensitive to height or depth SHOULD interpret positions as being at local ground or sea level.\n","externalDocs":{"url":"https://tools.ietf.org/html/rfc7946#section-3"},"type":"object","properties":{"type":{"type":"string","enum":["Feature","FeatureCollection","Point","MultiPoint","LineString","MultiLineString","Polygon","MultiPolygon","GeometryCollection"]},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type"],"discriminator":{"propertyName":"type"}},"Geometry":{"description":"Abstract type for all GeoJSon object except Feature and FeatureCollection\n","externalDocs":{"url":"https://tools.ietf.org/html/rfc7946#section-3"},"allOf":[{"$ref":"#/components/schemas/GeoJsonObject"},{"type":"object","properties":{"type":{"type":"string","enum":["Point","MultiPoint","LineString","MultiLineString","Polygon","MultiPolygon","GeometryCollection"]}},"required":["type"],"discriminator":{"propertyName":"type"}}]},"Feature":{"description":"GeoJSon 'Feature' object","externalDocs":{"url":"https://tools.ietf.org/html/rfc7946#section-3.2"},"allOf":[{"$ref":"#/components/schemas/GeoJsonObject"},{"type":"object","required":["geometry","properties"],"properties":{"geometry":{"allOf":[{"nullable":true},{"$ref":"#/components/schemas/Geometry"}]},"properties":{"type":"object","nullable":true},"id":{"oneOf":[{"type":"number"},{"type":"string"}]}}}]},"FeatureCollection":{"description":"GeoJSon 'FeatureCollection' object","externalDocs":{"url":"https://tools.ietf.org/html/rfc7946#section-3.3"},"allOf":[{"$ref":"#/components/schemas/GeoJsonObject"},{"type":"object","required":["features"],"properties":{"features":{"type":"array","items":{"$ref":"#/components/schemas/Feature"}}}}]},"Error":{"description":"Error object of what 3 words","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}