diff --git a/README.md b/README.md index ab8bbc8..223b45b 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,7 @@ weather.getCurrent().then(data => { * [setLocationByCoordinates][slocbycoor] * [setLocationByZipCode][slocbyzip] * [getLocation][gloc] + * [getAllLocations][gallloc] * [Getting & Manipulating Weather Data][gcur] * [getCurrent][gcur] * [getMinutelyForecast][gminutely] @@ -321,6 +322,26 @@ location = await weather.getLocation({locationName: "Tokio"}) ``` *See also:* [options][opt], [setLocationByName][slocbyname], [setLocationByCoordinates][slocbycoor] +## `async` getAllLocations(query, options = {}) + +**Description:** + +Getter for all locations from query + +**Arguments:** +* **query** - query used to search the locations +* **options** - options used only for this call (defaults to empty object) + +**Returns:** + +Array of [Location Objects][lobj] - `Array` + +**Example:** +```js +let locations = await weather.getAllLocations("London") +``` +*See also:* [options][opt] + ## `async` getCurrent(options = {}) **Description:** @@ -782,6 +803,7 @@ When using raw API the problem might be getting your head around how unorganised [slocbycoor]: #setlocationbycoordinateslat-lon [slocbyzip]:#setlocationbyzipcodezipcode [gloc]: #async-getlocationoptions +[gallloc]: #async-getAllLocationsquery-options-- [gcur]: #async-getcurrentoptions [gminutely]: #async-getminutelyforecastlimit--numberpositive_infinity-options-- [ghourly]: #async-gethourlyforecastlimit--numberpositive_infinity-options-- diff --git a/src/index.js b/src/index.js index 649679e..2a9798a 100644 --- a/src/index.js +++ b/src/index.js @@ -401,6 +401,21 @@ class OpenWeatherAPI { return data.length ? data[0] : null } + /** + * Getter for locations from query + * + * @param {String} query - query used to search the locations (`q` parameter [here](https://openweathermap.org/api/geocoding-api#direct_name)) + * @param {Options} [options={}] - options used only for this call + * @returns {Promise} all found locations + */ + async getAllLocations(query, options = {}) { + if (!query) throw new Error("No query") + options = await this.#parseOptions(options) + let response = await this.#fetch(`${API_ENDPOINT}${GEO_PATH}direct?q=${query}&limit=5&appid=${options.key}`) + let data = response.data + return data + } + // Weather getters /** diff --git a/test/getter_test.js b/test/getter_test.js index d3fba8d..46dc7be 100644 --- a/test/getter_test.js +++ b/test/getter_test.js @@ -19,6 +19,11 @@ describe("Getting tests:", function () { assert(location.name.toLowerCase().includes("new york")) }) + it("gets all locations", async () => { + let locations = await weather.getAllLocations("London") + assert(locations.length == 5) + }) + it("gets current", async () => { weather.setLocationByName("warsaw") let current = await weather.getCurrent() diff --git a/typings/index.d.ts b/typings/index.d.ts index 97a02df..fea8514 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -144,6 +144,14 @@ declare class OpenWeatherAPI { * @returns {Promise} location */ getLocation(options?: Options): Promise; + /** + * Getter for locations from query + * + * @param {String} query - query used to search the locations (`q` parameter [here](https://openweathermap.org/api/geocoding-api#direct_name)) + * @param {Options} [options={}] - options used only for this call + * @returns {Promise} all found locations + */ + getAllLocations(query: string, options?: Options): Promise; /** * Getter for current weather *