what3words API

https://github.com/what3words/w3w-node-wrapper
Admin
A JavaScript library wrapper that provides programmatic access to the what3words REST API for...
Tokens:11,463
Snippets:56
Trust Score:9.7
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install what3words API Package

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Commands to install the what3words API library using common package managers.

```shell
npm install @what3words/api
```

```shell
yarn add @what3words/api
```

--------------------------------

### JavaScript Usage Example

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Demonstrates how to instantiate and use the what3words JavaScript API wrapper in a Node.js environment.

```APIDOC
## JavaScript Usage

### Description
This code snippet shows how to initialize the what3words service in a JavaScript environment, including setting the API key, configuration, and transport.

### Method
Instantiation and Configuration

### Endpoint
N/A (Client-side library)

### Parameters
- **apiKey** (string) - Required - Your unique what3words API key.
- **config** (object) - Optional - Configuration object for the API host and version.
  - **host** (string) - Optional - The API host URL. Defaults to 'https://api.what3words.com'.
  - **apiVersion** (string) - Optional - The API version. Defaults to 'v3'.
- **transport** (object) - Optional - A custom transport object for making requests. Defaults to `fetchTransport()`.

### Request Example
```javascript
const what3words,
  { fetchTransport } = require('@what3words/api');

const apiKey = '<YOUR_API_KEY>';
const config = {
  host: 'https://api.what3words.com',
  apiVersion: 'v3',
};
const transport = fetchTransport(); // or you can import 'axiosTransport' instead
const w3wService = what3words(apiKey, config, { transport });

// you can uncomment the following lines to set your api key and config after instantiation of the w3w service
// w3wService.setApiKey(apiKey);
// w3wService.setConfig(config);
```

### Response
#### Success Response (200)
N/A (This is an initialization example)

#### Response Example
N/A
```

--------------------------------

### TypeScript Usage Example

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Illustrates how to set up the what3words API wrapper using TypeScript, including type definitions.

```APIDOC
## TypeScript Usage

### Description
This code snippet demonstrates how to initialize the what3words service in a TypeScript environment, leveraging type safety for API key, configuration, and transport.

### Method
Instantiation and Configuration

### Endpoint
N/A (Client-side library)

### Parameters
- **apiKey** (string) - Required - Your unique what3words API key.
- **config** (object) - Optional - Configuration object for the API host and version.
  - **host** (string) - Optional - The API host URL. Defaults to 'https://api.what3words.com'.
  - **apiVersion** (string) - Optional - The API version. Defaults to 'v3'.
- **transport** (object) - Optional - A custom transport object for making requests. Defaults to `axiosTransport()`.

### Request Example
```typescript
import what3words,
  { ApiVersion,
    Transport,
    What3wordsService,
    axiosTransport } from '@what3words/api';

const apiKey = '<YOUR_API_KEY>';
const config: {
  host: string;
  apiVersion: ApiVersion;
} = {
  host: 'https://api.what3words.com',
  apiVersion: ApiVersion.Version3,
};
const transport: Transport = axiosTransport();
const w3wService: What3wordsService = what3words(apiKey, config, { transport });

// code continues...
```

### Response
#### Success Response (200)
N/A (This is an initialization example)

#### Response Example
N/A
```

--------------------------------

### Install Transport Dependencies

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Commands to install the required peer dependencies for the built-in transport layers using npm or yarn.

```bash
npm install cross-fetch
npm install axios
yarn add cross-fetch
yarn add axios
```

--------------------------------

### Get Grid Section Data using what3words Node.js Wrapper

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Demonstrates how to retrieve a section of the 3m x 3m what3words grid using the Node.js wrapper. It shows how to fetch grid lines as JSON and as GeoJSON, suitable for map overlays. The bounding box input is validated to not exceed 4km corner to corner.

```javascript
import { GridSectionClient } from '@what3words/api';

// Using the service
const w3wService = what3words('YOUR_API_KEY');

// Get grid lines as JSON
const grid = await w3wService.gridSection({
  boundingBox: {
    southwest: { lat: 52.207988, lng: 0.116126 },
    northeast: { lat: 52.208867, lng: 0.11754 }
  }
});
console.log(grid);

// Get grid as GeoJSON (for mapping libraries)
const geoGrid = await w3wService.gridSection({
  boundingBox: {
    southwest: { lat: 52.207988, lng: 0.116126 },
    northeast: { lat: 52.208867, lng: 0.11754 }
  },
  format: 'geojson'
});
console.log(geoGrid);

// Using individual client
const client = GridSectionClient.init('YOUR_API_KEY');
const gridResult = await client.run({
  boundingBox: {
    southwest: { lat: 51.52, lng: -0.20 },
    northeast: { lat: 51.521, lng: -0.195 }
  }
});
```

--------------------------------

### Implement Custom HTTP Transports with what3words Node.js Wrapper

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Provides examples of creating custom HTTP transports for the what3words Node.js wrapper. This allows integration with existing HTTP libraries like superagent or adding custom logic such as logging and retries. It demonstrates how to use a custom transport with the service and how to wrap an existing transport with logging functionality.

```javascript
import what3words, { ClientRequest, TransportResponse } from '@what3words/api';
import superagent from 'superagent';

// Custom transport using superagent
function customTransport(request) {
  const { method, host, url, query = {}, headers = {}, body = {}, format } = request;

  return new Promise(resolve =>
    superagent[method](`${host}${url}`)
      .query({ ...query, format })
      .send(body || {})
      .set(headers)
      .end((err, res) => {
        if (err || !res) {
          return resolve({
            status: err?.status || 500,
            statusText: err?.response?.text || 'Internal Server Error',
            headers: err?.headers || {},
            body: err?.response?.text || null,
          });
        }
        resolve({
          status: res.status,
          statusText: res.text,
          headers: res.headers,
          body: res.body,
        });
      })
  );
}

// Use custom transport with service
const service = what3words('YOUR_API_KEY', {}, { transport: customTransport });

const languages = await service.availableLanguages();
console.log(languages);

// Custom transport with logging
function loggingTransport(baseTransport) {
  return async function(request) {
    console.log('Request:', request.method, request.url);
    const response = await baseTransport(request);
    console.log('Response:', response.status);
    return response;
  };
}

const fetchTransport = require('@what3words/api').fetchTransport;
const loggingService = what3words('YOUR_API_KEY', {}, {
  transport: loggingTransport(fetchTransport())
});
```

--------------------------------

### GET /autosuggest

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Returns a list of three-word address suggestions based on partial input, with support for geographic clipping and focus.

```APIDOC
## GET /autosuggest

### Description
Returns a list of three-word address suggestions based on partial input. Supports focusing results around a location, clipping to countries/regions, and handling voice input.

### Method
GET

### Endpoint
/autosuggest

### Parameters
#### Query Parameters
- **input** (string) - Required - The partial three-word address to suggest.
- **focus** (object) - Optional - Latitude and longitude to prioritize results.
- **clipToCountry** (array) - Optional - List of ISO country codes to restrict results.
- **inputType** (string) - Optional - The type of input (e.g., GenericVoice).

### Request Example
{
  "input": "filled.count.s",
  "focus": {"lat": 51.520847, "lng": -0.195521}
}

### Response
#### Success Response (200)
- **suggestions** (array) - List of suggested addresses with metadata.

#### Response Example
{
  "suggestions": [
    { "words": "filled.count.soap", "nearestPlace": "Bayswater, London", "country": "GB" }
  ]
}
```

--------------------------------

### Initialize what3words Service (JavaScript)

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Demonstrates how to initialize the what3words service with an API key and optional configuration. Supports custom transports like fetch or axios for HTTP requests. API key and configuration can be set during initialization or updated later.

```javascript
const what3words, { fetchTransport, axiosTransport } = require('@what3words/api');

// Initialize with API key and default configuration
const apiKey = 'YOUR_API_KEY';
const w3wService = what3words(apiKey);

// Or with custom configuration and transport
const config = {
  host: 'https://api.what3words.com',
  apiVersion: 'v3',
};
const transport = fetchTransport(); // or axiosTransport()
const w3wService = what3words(apiKey, config, { transport });

// Set API key after initialization
w3wService.setApiKey('NEW_API_KEY');

// Set configuration after initialization
w3wService.setConfig({
  host: 'https://api.what3words.com',
  apiVersion: 'v3',
  headers: { 'Custom-Header': 'value' }
});
```

--------------------------------

### Use Autosuggest Client

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Shows how to initialize the AutosuggestClient and perform a search query to retrieve address suggestions.

```typescript
import { AutosuggestClient, AutosuggestOptions, AutosuggestResponse } from '@what3words/api';

const API_KEY = '<YOUR_API_KEY>';
const client: AutosuggestClient = AutosuggestClient.init(API_KEY);
const options: AutosuggestOptions = { input: 'filled.count.s' };
client.run(options).then((res: AutosuggestResponse) => console.log(`suggestions for "${options.input}"`, res));
```

--------------------------------

### Initialize what3words Service

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Demonstrates how to instantiate the what3words service with an API key, configuration, and transport layer in both JavaScript and TypeScript.

```javascript
const what3words, { fetchTransport } = require('@what3words/api');
const apiKey = '<YOUR_API_KEY>';
const config = { host: 'https://api.what3words.com', apiVersion: 'v3' };
const transport = fetchTransport();
const w3wService = what3words(apiKey, config, { transport });
```

```typescript
import what3words, { ApiVersion, Transport, What3wordsService, axiosTransport } from '@what3words/api';
const apiKey = '<YOUR_API_KEY>';
const config: { host: string; apiVersion: ApiVersion } = { host: 'https://api.what3words.com', apiVersion: ApiVersion.Version3 };
const transport: Transport = axiosTransport();
const w3wService: What3wordsService = what3words(apiKey, config, { transport });
```

--------------------------------

### Implement Custom API Transport

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Demonstrates how to create a custom transport function using superagent to handle API requests, which can be passed to the What3wordsService during initialization.

```typescript
import what3words, { ClientRequest, TransportResponse } from '@what3words/api';
import superagent from 'superagent';

const API_KEY = '<YOUR_API_KEY>';
const config = {};

function customTransport<ResponseType>(
  request: ClientRequest
): Promise<TransportResponse<ResponseType>> {
  const { method, host, url, query = {}, headers = {}, body = {}, format } = request;
  return new Promise(resolve =>
    superagent[method](`${host}${url}`)
      .query({ ...query, format })
      .send(body || {})
      .set(headers)
      .end((err, res) => {
        if (err || !res)
          return resolve({
            status: err.status || 500,
            statusText: err.response.text || 'Internal Server Error',
            headers: err.headers || {},
            body: err.response.text || null,
          });
        const response: TransportResponse<ResponseType> = {
          status: res.status,
          statusText: res.text,
          headers: res.headers,
          body: res.body,
        };
        resolve(response);
      })
  );
}

const service = what3words(API_KEY, config, { transport: customTransport });
service.availableLanguages().then(({ languages }) => console.log('Available languages', languages));
```

--------------------------------

### Autosuggest Three Word Addresses with Node.js

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Provides a list of three-word address suggestions based on partial input. Supports focusing results around a location, clipping to countries/regions, and handling voice input. Essential for building address input interfaces.

```javascript
import {
  AutosuggestClient,
  AutosuggestOptions,
  AutosuggestResponse,
  AutosuggestInputType
} from '@what3words/api';

// Using the service
const w3wService = what3words('YOUR_API_KEY');

// Basic autosuggest
const suggestions = await w3wService.autosuggest({
  input: 'filled.count.s'
});
console.log(suggestions);
// { 
//   suggestions: [
//     { country: 'GB', nearestPlace: 'Bayswater, London', words: 'filled.count.soap', distanceToFocusKm: 0, rank: 1, language: 'en' },
//     { country: 'US', nearestPlace: 'Springfield, Missouri', words: 'filled.count.sand', distanceToFocusKm: 0, rank: 2, language: 'en' },
//     ...
//   ]
// }

// With focus point (prioritizes results near location)
const focusedSuggestions = await w3wService.autosuggest({
  input: 'filled.count.s',
  focus: { lat: 51.520847, lng: -0.195521 },
  nFocusResults: 3
});

// Clip to specific countries
const ukSuggestions = await w3wService.autosuggest({
  input: 'index.home.r',
  clipToCountry: ['GB', 'IE'],
  nResults: 5
});

// Clip to bounding box
const boxSuggestions = await w3wService.autosuggest({
  input: 'filled.count.s',
  clipToBoundingBox: {
    southwest: { lat: 51.0, lng: -0.5 },
    northeast: { lat: 52.0, lng: 0.5 }
  }
});

// Clip to circle
const circleSuggestions = await w3wService.autosuggest({
  input: 'filled.count.s',
  clipToCircle: {
    center: { lat: 51.520847, lng: -0.195521 },
    radius: 10 // kilometers
  }
});

// Clip to polygon
const polygonSuggestions = await w3wService.autosuggest({
  input: 'filled.count.s',
  clipToPolygon: [
    { lat: 51.0, lng: -0.5 },
    { lat: 51.0, lng: 0.5 },
    { lat: 52.0, lng: 0.5 },
    { lat: 52.0, lng: -0.5 },
    { lat: 51.0, lng: -0.5 } // closed polygon
  ]
});

// Voice input handling
const voiceSuggestions = await w3wService.autosuggest({
  input: 'filled count soap',
  inputType: AutosuggestInputType.GenericVoice,
  language: 'en'
});

// Track selection for analytics
const selected = suggestions.suggestions[0];
await w3wService.autosuggestSelection(selected);
```

--------------------------------

### Leverage TypeScript for Type-Safe what3words API Interactions

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Illustrates the full TypeScript support provided by the what3words Node.js wrapper. It shows how to use exported types for requests, responses, and configuration, enabling type-safe development for API interactions, including defining coordinates, bounds, autosuggest options, and handling typed responses.

```typescript
import what3words, {
  ApiVersion,
  Transport,
  What3wordsService,
  ApiClientConfiguration,
  AutosuggestOptions,
  AutosuggestResponse,
  ConvertTo3waOptions,
  ConvertToCoordinatesOptions,
  GridSectionOptions,
  LocationJsonResponse,
  LocationGeoJsonResponse,
  FeatureCollectionResponse,
  Coordinates,
  Bounds,
  axiosTransport,
} from '@what3words/api';

// Typed configuration
const config: ApiClientConfiguration = {
  host: 'https://api.what3words.com',
  apiVersion: ApiVersion.Version3,
  headers: { 'X-Custom': 'header' }
};

// Typed transport
const transport: Transport = axiosTransport();

// Typed service
const w3wService: What3wordsService = what3words('YOUR_API_KEY', config, { transport });

// Typed coordinates
const coords: Coordinates = { lat: 51.520847, lng: -0.195521 };

// Typed bounds
const bounds: Bounds = {
  southwest: { lat: 51.0, lng: -0.5 },
  northeast: { lat: 52.0, lng: 0.5 }
};

// Typed autosuggest options
const autosuggestOpts: AutosuggestOptions = {
  input: 'filled.count.s',
  focus: coords,
  nResults: 5,
  clipToBoundingBox: bounds
};

// Typed response
const suggestions: AutosuggestResponse = await w3wService.autosuggest(autosuggestOpts);

// Typed conversion
const location: LocationJsonResponse = await w3wService.convertToCoordinates({
  words: 'filled.count.soap'
});

// Typed GeoJSON response
const geoLocation: FeatureCollectionResponse<LocationGeoJsonResponse> =
  await w3wService.convertToCoordinates({
    words: 'filled.count.soap',
    format: 'geojson'
  });
```

--------------------------------

### Convert Coordinates to Three Word Address (JavaScript)

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Illustrates how to convert geographic coordinates (latitude and longitude) into a three-word address. Allows specifying the desired language for the output. Supports GeoJSON format and can be used via the service or the ConvertTo3waClient.

```javascript
import {
  ConvertTo3waClient,
  ConvertTo3waOptions,
  LocationJsonResponse
} from '@what3words/api';

// Using the service
const w3wService = what3words('YOUR_API_KEY');

// Convert coordinates to 3wa in English (default)
const result = await w3wService.convertTo3wa({
  coordinates: { lat: 51.520847, lng: -0.195521 }
});
console.log(result);
// { 
//   country: 'GB',
//   nearestPlace: 'Bayswater, London',
//   words: 'filled.count.soap',
//   language: 'en',
//   map: 'https://w3w.co/filled.count.soap',
//   coordinates: { lat: 51.520847, lng: -0.195521 },
//   square: { southwest: {...}, northeast: {...} }
// }

// Convert to German 3wa
const germanResult = await w3wService.convertTo3wa({
  coordinates: { lat: 51.520847, lng: -0.195521 },
  language: 'de'
});
console.log(germanResult.words); // German three word address

// GeoJSON format
const geoResult = await w3wService.convertTo3wa({
  coordinates: { lat: 51.520847, lng: -0.195521 },
  format: 'geojson'
});

// Using individual client
const client = ConvertTo3waClient.init('YOUR_API_KEY');
const location = await client.run({
  coordinates: { lat: 52.208867, lng: 0.11754 },
  language: 'fr'
});
```

--------------------------------

### API Endpoint: Autosuggest

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Provides suggestions for 3 word addresses based on partial input.

```APIDOC
## POST /autosuggest

### Description
This endpoint provides a list of suggested 3 word addresses based on a partial or potentially incorrect input.

### Method
POST

### Endpoint
`/v3/autosuggest`

### Parameters
#### Query Parameters
- **search** (string) - Required - The partial or incorrect 3 word address input.
- **lang** (string) - Optional - The language for suggestions. Defaults to 'en'.
- **limit** (integer) - Optional - The maximum number of suggestions to return. Defaults to 10.
- **clip_to_country** (string) - Optional - Limits suggestions to a specific country (ISO 3166-1 alpha-2 code).
- **clip_to_bounding_box** (string) - Optional - Limits suggestions to a bounding box defined by `south, west, north, east` coordinates.
- **clip_to_circle** (string) - Optional - Limits suggestions to a circle defined by `lat, lng, radius_km`.
- **prefer_last_type_in_square** (boolean) - Optional - Prioritizes suggestions within the last type-in square. Defaults to false.

### Request Example
```json
{
  "search": "index.home."
}
```

### Response
#### Success Response (200)
- **suggestions** (array) - A list of suggested 3 word addresses.
  - **words** (string) - The suggested 3 word address.
  - **language** (string) - The language of the suggested address.
  - **duration_seconds** (number) - The time taken to generate the suggestion in seconds.
  - **rank** (integer) - The rank of the suggestion.
  - **nearest_place** (string) - The nearest place to the suggested address.
  - **country** (string) - The country of the suggested address.
  - **map_url** (string) - A URL to view the suggested address on a map.
  - **square** (object) - Details about the square.
    - **south_lat** (number)
    - **west_lng** (number)
    - **north_lat** (number)
    - **east_lng** (number)
  - **core_words** (string) - The core part of the 3 word address.

#### Response Example
```json
{
  "suggestions": [
    {
      "words": "index.home.raft",
      "language": "en",
      "duration_seconds": 0.001,
      "rank": 1,
      "nearest_place": "",
      "country": "GB",
      "map_url": "https://map.what3words.com/index.home.raft",
      "square": {
        "south_lat": 51.521245,
        "west_lng": -0.191815,
        "north_lat": 51.521275,
        "east_lng": -0.191775
      },
      "core_words": "index.home.raft"
    }
  ]
}
```
```

--------------------------------

### Autosuggest API

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Provides suggestions for 3-word addresses based on user input.

```APIDOC
## GET /autosuggest

### Description
Retrieves a list of 3-word address suggestions based on the provided input string.

### Request Example
{
  "input": "filled.count.s"
}

### Response
#### Success Response (200)
- **suggestions** (array) - List of suggested 3-word addresses
```

--------------------------------

### Retrieve Supported Languages with Node.js

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Retrieves the list of all languages supported by the what3words API. Each language includes its ISO code, English name, and native name.

```javascript
import { AvailableLanguagesClient, AvailableLanguagesResponse } from '@what3words/api';

// Using the service
const w3wService = what3words('YOUR_API_KEY');

const languages = await w3wService.availableLanguages();
console.log(languages);
// { 
//   languages: [
//     { code: 'en', name: 'English', nativeName: 'English' },
//     { code: 'de', name: 'German', nativeName: 'Deutsch' },
//     { code: 'fr', name: 'French', nativeName: 'Français' },
//     { code: 'es', name: 'Spanish', nativeName: 'Español' },
//     ...
//   ]
// }

// Using individual client
const client = AvailableLanguagesClient.init('YOUR_API_KEY');
const result = await client.run();
console.log(result.languages.map(l => l.code)); // ['en', 'de', 'fr', ...]
```

--------------------------------

### Retrieve Available Languages (TypeScript)

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Fetches a list of all languages supported by the what3words API. This function requires an API key for initialization and returns the list of languages in a JSON format.

```typescript
import {
  AvailableLanguagesClient,
  AvailableLanguagesResponse,
} from '@what3words/api';

const API_KEY = '<YOUR_API_KEY>';
const client: AvailableLanguagesClient = AvailableLanguagesClient.init(API_KEY);
client
  .run()
  .then((res: AvailableLanguagesResponse) =>
    console.log('Available Languages', res)
  );
```

--------------------------------

### Convert Three Word Address to Coordinates (JavaScript)

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Shows how to convert a three-word address into its corresponding latitude and longitude coordinates using the what3words API. Supports both JSON and GeoJSON response formats. Can be used via the main service or the individual ConvertToCoordinatesClient.

```javascript
import {
  ConvertToCoordinatesClient,
  ConvertToCoordinatesOptions,
  LocationJsonResponse,
  FeatureCollectionResponse,
  LocationGeoJsonResponse
} from '@what3words/api';

// Using the service
const w3wService = what3words('YOUR_API_KEY');

// JSON response (default)
const locationJson = await w3wService.convertToCoordinates({
  words: 'filled.count.soap'
});
console.log(locationJson);
// { 
//   country: 'GB',
//   nearestPlace: 'Bayswater, London',
//   words: 'filled.count.soap',
//   language: 'en',
//   map: 'https://w3w.co/filled.count.soap',
//   coordinates: { lat: 51.520847, lng: -0.195521 },
//   square: {
//     southwest: { lat: 51.520833, lng: -0.195543 },
//     northeast: { lat: 51.52086, lng: -0.195499 }
//   }
// }

// GeoJSON response
const locationGeoJson = await w3wService.convertToCoordinates({
  words: 'filled.count.soap',
  format: 'geojson'
});
console.log(locationGeoJson);
// { 
//   type: 'FeatureCollection',
//   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: '...' }
//   }]
// }

// Using individual client
const client = ConvertToCoordinatesClient.init('YOUR_API_KEY');
const result = await client.run({ words: 'index.home.raft' });
```

--------------------------------

### POST /autosuggest-selection

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Tracks a user's selection from the autosuggest results for analytics purposes.

```APIDOC
## POST /autosuggest-selection

### Description
Tracks a user's selection from the autosuggest results for analytics purposes.

### Method
POST

### Endpoint
/autosuggest-selection

### Request Body
- **selection** (object) - Required - The suggestion object selected by the user.

### Request Example
{
  "words": "filled.count.soap",
  "rank": 1
}
```

--------------------------------

### Convert Words to Coordinates

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Demonstrates how to use the ConvertToCoordinatesClient to resolve three-word addresses into coordinates, supporting both standard JSON and GeoJSON formats.

```typescript
import { ConvertToCoordinatesClient, ConvertToCoordinatesOptions, FeatureCollectionResponse, LocationGeoJsonResponse, LocationJsonResponse } from '@what3words/api';

const API_KEY = '<YOUR_API_KEY>';
const client: ConvertToCoordinatesClient = ConvertToCoordinatesClient.init(API_KEY);
const options: ConvertToCoordinatesOptions = { words: 'filled.count.soap' };

client.run({ ...options, format: 'json' }).then((res: LocationJsonResponse) => console.log('Convert to coordinates', res));

client.run({ ...options, format: 'geojson' }).then((res: FeatureCollectionResponse<LocationGeoJsonResponse>) => console.log('Convert to coordinates', res));
```

--------------------------------

### API Endpoint: Grid Section

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Retrieves a section of the what3words grid for a given bounding box.

```APIDOC
## GET /grid-section

### Description
This endpoint retrieves a section of the what3words 3m x 3m grid for a specified bounding box.

### Method
GET

### Endpoint
`/v3/grid-section`

### Parameters
#### Query Parameters
- **bounding-box** (string) - Required - The bounding box defined by `south, west, north, east` coordinates.

### Request Example
```json
{
  "bounding-box": "51.521,-0.192,51.522,-0.191"
}
```

### Response
#### Success Response (200)
- **geometry** (object) - GeoJSON representation of the grid section.
- **features** (array) - An array of grid square features.
  - **type** (string) - Type of the feature (e.g., 'Feature').
  - **properties** (object) - Properties of the grid square.
    - **cell_type** (string) - Type of the cell ('normal' or 'square').
    - **words** (string) - The 3 word address for the grid square.
    - **hex_code** (string) - The hex code for the grid square.
    - **line** (string) - The line for the grid square.
    - **area** (string) - The area for the grid square.
    - **square** (object) - Details about the square.
      - **south_lat** (number)
      - **west_lng** (number)
      - **north_lat** (number)
      - **east_lng** (number)
  - **type** (string) - Type of the geometry ('Polygon').
  - **coordinates** (array) - Coordinates of the grid square polygon.

#### Response Example
```json
{
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-0.191815, 51.521245],
        [-0.191775, 51.521245],
        [-0.191775, 51.521275],
        [-0.191815, 51.521275],
        [-0.191815, 51.521245]
      ]
    ]
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "cell_type": "normal",
        "words": "index.home.raft",
        "hex_code": "",
        "line": "",
        "area": "",
        "square": {
          "south_lat": 51.521245,
          "west_lng": -0.191815,
          "north_lat": 51.521275,
          "east_lng": -0.191775
        }
      },
      "type": "Polygon",
      "coordinates": [
        [
          [-0.191815, 51.521245],
          [-0.191775, 51.521245],
          [-0.191775, 51.521275],
          [-0.191815, 51.521275],
          [-0.191815, 51.521245]
        ]
      ]
    }
  ]
}
```
```

--------------------------------

### API Endpoint: Available Languages

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Retrieves a list of all languages supported by the what3words API.

```APIDOC
## GET /languages

### Description
This endpoint returns a list of all languages supported by the what3words API, including their language codes.

### Method
GET

### Endpoint
`/v3/languages`

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **languages** (array) - A list of supported languages.
  - **code** (string) - The language code (e.g., 'en').
  - **name** (string) - The full name of the language (e.g., 'English').
  - **native_name** (string) - The native name of the language (e.g., 'English').

#### Response Example
```json
{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "native_name": "English"
    },
    {
      "code": "fr",
      "name": "French",
      "native_name": "Français"
    }
  ]
}
```
```

--------------------------------

### API Endpoint: Convert to Coordinates

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Converts a 3 word address to its corresponding latitude and longitude coordinates.

```APIDOC
## POST /convert-to-coordinates

### Description
This endpoint converts a given 3 word address into its geographical coordinates (latitude and longitude).

### Method
POST

### Endpoint
`/v3/convert-to-coordinates`

### Parameters
#### Query Parameters
- **addr** (string) - Required - The 3 word address to convert.
- **language** (string) - Optional - The language of the 3 word address. Defaults to 'en'.
- **format** (string) - Optional - The desired output format for coordinates. Possible values: 'json', 'geojson'. Defaults to 'json'.

### Request Example
```json
{
  "addr": "index.home.raft"
}
```

### Response
#### Success Response (200)
- **coordinates** (object) - The geographical coordinates.
  - **lat** (number) - Latitude.
  - **lng** (number) - Longitude.
- **language** (string) - The language of the 3 word address.
- **the3words** (string) - The 3 word address.

#### Response Example
```json
{
  "coordinates": {
    "lat": 51.521257,
    "lng": -0.191803
  },
  "language": "en",
  "the3words": "index.home.raft"
}
```
```

--------------------------------

### Validate Three Word Addresses with Node.js

Source: https://context7.com/what3words/w3w-node-wrapper/llms.txt

Methods to check if a string could be a three-word address format and validate against the API. Useful for input validation before making conversion requests.

```javascript
import { AutosuggestClient } from '@what3words/api';

const client = AutosuggestClient.init('YOUR_API_KEY');

// Find all possible 3wa patterns in text (does not validate with API)
const found = client.findPossible3wa('Meet me at filled.count.soap tomorrow');
console.log(found); // ['filled.count.soap']

const multipleFound = client.findPossible3wa('Address 1: filled.count.soap, Address 2: index.home.raft');
console.log(multipleFound); // ['filled.count.soap', 'index.home.raft']

const notFound = client.findPossible3wa('No address here');
console.log(notFound); // []

// Check if string matches 3wa format (does not validate with API)
const isPossible = client.isPossible3wa('filled.count.soap');
console.log(isPossible); // true

const notPossible = client.isPossible3wa('filled.count');
console.log(notPossible); // false

const withExtraText = client.isPossible3wa('Meet me at filled.count.soap');
console.log(withExtraText); // false (must be exact match)

// Validate 3wa exists via API call
const isValid = await client.isValid3wa('filled.count.soap');
console.log(isValid); // true

const isInvalid = await client.isValid3wa('filled.count.negative');
console.log(isInvalid); // false (not a real address)
```

--------------------------------

### Input Validation for 3 Word Addresses (TypeScript)

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Provides functions to validate and check for possible 3 word address patterns within strings. `findPossible3wa` returns an array of potential 3 word addresses found in a string, `isPossible3wa` checks if a string contains a possible 3 word address (returning boolean), and `isValid3wa` validates if a given string is a correct 3 word address (returning a Promise<boolean>).

```typescript
import {
  GridSectionClient,
  GridSectionOptions,
  FeatureCollectionResponse,
  GridSectionGeoJsonResponse,
  GridSectionJsonResponse,
} from '../src';

const API_KEY = '<YOUR_API_KEY>';
const client: GridSectionClient = GridSectionClient.init(API_KEY);
const options: GridSectionOptions = {
  boundingBox: {
    southwest: { lat: 52.208867, lng: 0.11754 },
    northeast: { lat: 52.207988, lng: 0.116126 },
  },
};

// Search a string for any character sequences that could be three word addresses
client.findPossible3wa('filled.count.soap'); // returns ['filled.count.soap']
client.findPossible3wa(
  'this string contains a three word address substring: filled.count.soap'
); // returns ['filled.count.soap']
client.findPossible3wa('filled.count'); // returns []

// Search a string for any character sequences that could be three word addresses
client.isPossible3wa('filled.count.soap'); // returns true
client.isPossible3wa(
  'this string contains a three word address substring: filled.count.soap'
); // returns false
client.isPossible3wa('filled.count'); // returns false

// Search a string for any character sequences that could be three word addresses
client.isValid3wa('filled.count.soap'); // returns Promise<true>
client.isValid3wa(
  'this string contains a three word address substring: filled.count.soap'
); // returns Promise<false>
client.isValid3wa('filled.count.negative'); // returns Promise<false>
```

--------------------------------

### Transport Configuration

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Defines the structure for custom transport functions used to execute API requests.

```APIDOC
## Transport Interface

### Description
The transport function executes requests against the what3words API. It accepts a ClientRequest object and returns a Promise resolving to a TransportResponse.

### ClientRequest Properties
- **host** (string) - Required - API host URL
- **url** (string) - Required - Endpoint path
- **method** (string) - Required - 'get' or 'post'
- **query** (object) - Optional - Query parameters
- **headers** (object) - Optional - Request headers
- **body** (object) - Optional - Request body
- **format** (string) - Required - 'json' or 'geojson'

### TransportResponse Properties
- **status** (number) - Required - HTTP status code
- **statusText** (string) - Required - Status message
- **body** (any) - Required - Response data
- **headers** (object) - Optional - Response headers
```

--------------------------------

### Query Grid Section by Bounding Box (TypeScript)

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Retrieves a grid section within a specified bounding box defined by southwest and northeast coordinates. Supports returning results in JSON and GeoJSON formats. The bounding box has a maximum size constraint of 4km corner to corner.

```typescript
import {
  GridSectionClient,
  GridSectionOptions,
  FeatureCollectionResponse,
  GridSectionGeoJsonResponse,
  GridSectionJsonResponse,
} from '../src';

const API_KEY = '<YOUR_API_KEY>';
const client: GridSectionClient = GridSectionClient.init(API_KEY);
const options: GridSectionOptions = {
  boundingBox: {
    southwest: { lat: 52.208867, lng: 0.11754 },
    northeast: { lat: 52.207988, lng: 0.116126 },
  },
};

// If you want to retrieve the JSON response from our API
client
  .run({ ...options, format: 'json' }) // { format: 'json' } is the default response
  .then((res: GridSectionJsonResponse) => console.log('Grid Section', res));

// If you want to retrieve the JSON response from our API
client
  .run({ ...options, format: 'geojson' }) // { format: 'json' } is the default response
  .then((res: FeatureCollectionResponse<GridSectionGeoJsonResponse>) =>
    console.log('Grid Section', res)
  );
```

--------------------------------

### Convert Coordinates to 3 Word Address (TypeScript)

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Converts geographical coordinates (latitude and longitude) into a 3 word address using the what3words API. It supports returning results in both JSON and GeoJSON formats. Requires an API key for initialization.

```typescript
import {
  ConvertTo3waClient,
  ConvertTo3waOptions,
  FeatureCollectionResponse,
  LocationGeoJsonResponse,
  LocationJsonResponse,
} from '@what3words/api';

const API_KEY = '<YOUR_API_KEY>';
const client: ConvertTo3waClient = ConvertTo3waClient.init(API_KEY);
const options: ConvertTo3waOptions = {
  coordinates: { lat: 51.520847, lng: -0.195521 },
};

// If you want to retrieve the JSON response from our API
client
  .run({ ...options, format: 'json' }) // { format: 'json' } is the default response
  .then((res: LocationJsonResponse) => console.log('Convert to 3wa', res));

// If you want to retrieve the GeoJsonResponse from our API
client
  .run({ ...options, format: 'geojson' })
  .then((res: FeatureCollectionResponse<LocationGeoJsonResponse>) =>
    console.log('Convert to 3wa', res)
  );
```

--------------------------------

### API Endpoint: Convert to 3 Word Address

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Converts geographical coordinates (latitude and longitude) to a 3 word address.

```APIDOC
## POST /convert-to-3wa

### Description
This endpoint converts a given latitude and longitude into its corresponding 3 word address.

### Method
POST

### Endpoint
`/v3/convert-to-3wa`

### Parameters
#### Query Parameters
- **latitude** (number) - Required - The latitude of the location.
- **longitude** (number) - Required - The longitude of the location.
- **language** (string) - Optional - The desired language for the 3 word address. Defaults to 'en'.

### Request Example
```json
{
  "latitude": 51.521257,
  "longitude": -0.191803
}
```

### Response
#### Success Response (200)
- **coordinates** (object) - The input geographical coordinates.
  - **lat** (number) - Latitude.
  - **lng** (number) - Longitude.
- **language** (string) - The language of the generated 3 word address.
- **the3words** (string) - The generated 3 word address.

#### Response Example
```json
{
  "coordinates": {
    "lat": 51.521257,
    "lng": -0.191803
  },
  "language": "en",
  "the3words": "index.home.raft"
}
```
```

--------------------------------

### Convert to Coordinates API

Source: https://github.com/what3words/w3w-node-wrapper/blob/main/README.md

Converts a 3-word address into geographic coordinates.

```APIDOC
## GET /convert-to-coordinates

### Description
Converts a valid 3-word address into latitude and longitude coordinates.

### Parameters
- **words** (string) - Required - The 3-word address to convert
- **format** (string) - Optional - 'json' or 'geojson'

### Request Example
{
  "words": "filled.count.soap",
  "format": "json"
}

### Response
#### Success Response (200)
- **coordinates** (object) - Latitude and longitude of the location
```
Tokens:
Raw