### Install weather-js

Source: https://github.com/devfacet/weather/blob/master/README.md

Install the weather-js package using npm. This is the first step before using the module in your project.

```bash
npm install weather-js
```

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

### Request-Scoped Configuration Example

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Configuration is provided per-request through the options object. This example shows the available properties for the weather.find() function.

```javascript
weather.find({
  search: 'London',         // Required: location name or ZIP code
  degreeType: 'C',          // Optional, default 'F'
  lang: 'en-US',            // Optional, language culture code
  timeout: 15000            // Optional, timeout in ms
}, callback)
```

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

### Weather Module Usage Example

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Demonstrates how to require and use the weather-js module, specifically its 'find' function.

```javascript
var weather = require('weather-js');
// weather.find() is available as the primary API
```

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

### Sample Weather API Response

Source: https://github.com/devfacet/weather/blob/master/README.md

Example JSON output from the weather.find method, showing location details, current weather, and a multi-day forecast.

```json
[
  {
    "location": {
      "name": "San Francisco, CA",
      "lat": "37.777",
      "long": "-122.42",
      "timezone": "-7",
      "alert": "",
      "degreetype": "F",
      "imagerelativeurl": "http://blob.weather.microsoft.com/static/weather4/en-us/"
    },
    "current": {
      "temperature": "70",
      "skycode": "32",
      "skytext": "Sunny",
      "date": "2017-03-14",
      "observationtime": "13:15:00",
      "observationpoint": "San Francisco, California",
      "feelslike": "70",
      "humidity": "59",
      "winddisplay": "3 mph West",
      "day": "Tuesday",
      "shortday": "Tue",
      "windspeed": "3 mph",
      "imageUrl": "http://blob.weather.microsoft.com/static/weather4/en-us/law/32.gif"
    },
    "forecast": [
      {
        "low": "52",
        "high": "69",
        "skycodeday": "31",
        "skytextday": "Clear",
        "date": "2017-03-13",
        "day": "Monday",
        "shortday": "Mon",
        "precip": ""
      },
      {
        "low": "52",
        "high": "70",
        "skycodeday": "34",
        "skytextday": "Mostly Sunny",
        "date": "2017-03-14",
        "day": "Tuesday",
        "shortday": "Tue",
        "precip": "10"
      },
      {
        "low": "56",
        "high": "63",
        "skycodeday": "26",
        "skytextday": "Cloudy",
        "date": "2017-03-15",
        "day": "Wednesday",
        "shortday": "Wed",
        "precip": "20"
      },
      {
        "low": "50",
        "high": "64",
        "skycodeday": "28",
        "skytextday": "Mostly Cloudy",
        "date": "2017-03-16",
        "day": "Thursday",
        "shortday": "Thu",
        "precip": "10"
      },
      {
        "low": "53",
        "high": "67",
        "skycodeday": "32",
        "skytextday": "Sunny",
        "date": "2017-03-17",
        "day": "Friday",
        "shortday": "Fri",
        "precip": "10"
      }
    ]
  }
]
```

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

### Weather API Error Handling Example

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Demonstrates how to handle different types of errors (string, Error object) and empty results returned by the weather API callback.

```javascript
weather.find(options, function(err, result) {
  if (err) {
    // Handle error
    if (typeof err === 'string') {
      console.error('Validation error:', err);
    } else if (err instanceof Error) {
      console.error('Request error:', err.message);
    }
    return;
  }
  
  if (result.length === 0) {
    console.log('No locations found');
    return;
  }
  
  // Process results
});
```

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

### Construct Weather Icon Image URL

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Build the image URL for weather icons by concatenating the base URL, icon type, skycode, and file extension. This example shows how to construct the URL for current conditions.

```javascript
var imageUrl = result[0].location.imagerelativeurl + 'law/' + result[0].current.skycode + '.gif';
// Example: http://blob.weather.microsoft.com/static/weather4/en-us/law/32.gif
```

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

### Wrap Callback API in Promises

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Use this function to wrap the callback-based `find()` method in a Promise for use with async/await syntax. No specific setup is required beyond importing the weather module.

```javascript
function findAsync(options) {
  return new Promise(function(resolve, reject) {
    weather.find(options, function(err, result) {
      if (err) reject(err);
      else resolve(result);
    });
  });
}
```

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

### Find Weather Data

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Use this snippet to find weather data for a specified location. Ensure the 'weather-js' package is installed and required. Handles potential errors and location not found scenarios.

```javascript
var weather = require('weather-js');

weather.find({
  search: 'San Francisco, CA',
  degreeType: 'F'
}, function(err, result) {
  if (err) return console.error(err);
  
  if (result.length === 0) {
    console.log('Location not found');
    return;
  }
  
  var location = result[0];
  console.log(location.location.name);           // "San Francisco, CA"
  console.log(location.current.temperature);    // "70"
  console.log(location.current.skytext);        // "Sunny"
  console.log(location.forecast[0].skytextday); // "Clear"
});
```

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

### Weather Search with All Options Specified

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Demonstrates specifying all available configuration options: search term, degree type, language, and timeout.

```javascript
weather.find({
  search: 'Tokyo',
  degreeType: 'C',
  lang: 'ja-JP',  // Japanese (if supported by service)
  timeout: 15000
}, function(err, result) {
  // Full configuration specified
});
```

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

### Default Configuration Values

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Sets the default language, temperature scale, and timeout for weather requests.

```javascript
defLang       = 'en-US'     // Language
defDegreeType = 'F'         // Temperature scale
defTimeout    = 10000       // Timeout: 10 seconds
```

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

### weather.find(options, callback) Signature

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

This is the only public API entry point for the weather module. It queries the MSN Weather service and returns results asynchronously via a callback.

```javascript
weather.find(options, callback)
```

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

### Retrieve 5-Day Forecast

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Fetches the 5-day forecast for a given location and logs the date and high temperature for each day.

```javascript
weather.find({
  search: 'London'
}, function(err, result) {
  if (err) return console.error(err);
  if (result[0].forecast) {
    result[0].forecast.forEach(function(day) {
      console.log(day.date + ': ' + day.high + '°');
    });
  }
});
```

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

### Basic Weather Query

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Perform a basic weather query for a specific location and log the current temperature. Requires the 'weather-js' module to be required.

```javascript
var weather = require('weather-js');

weather.find({search: 'San Francisco, CA'}, function(err, result) {
  if (err) return console.error(err);
  console.log(result[0].current.temperature);
});
```

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

### weather.find(options, callback)

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Retrieves weather information for a specified location using provided options and returns results via a callback function.

```APIDOC
## weather.find(options, callback)

### Description
Retrieves weather information for a specified location.

### Parameters
#### options (object) - Required
Configuration with location search and preferences.
- **search** (string) - Required - Location name or ZIP code
- **degreeType** (string) - Optional - 'F' or 'C', default 'F'
- **lang** (string) - Optional - Language culture code, default 'en-US'
- **timeout** (number) - Optional - Request timeout in ms, default 10000

#### callback (function) - Required
`function(err, result)` called when request completes.
- **err**: null on success, Error object or error string on failure
- **result**: Array of weather objects (empty array if location not found)

### Returns
void (all results delivered via callback)
```

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

### Weather Search Configuration

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Configure weather searches using the `options` parameter in `weather.find()`. The `search` parameter is required, while `degreeType`, `lang`, and `timeout` are optional.

```javascript
weather.find({
  search: 'San Francisco, CA',  // Required
  degreeType: 'F',              // Optional, default 'F'
  lang: 'en-US',                // Optional, default 'en-US'
  timeout: 10000                // Optional, default 10000ms
}, callback)
```

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

### weather.find()

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Retrieves current weather information and a 5-day forecast for a specified location from the MSN Weather service.

```APIDOC
## weather.find()

### Description
Retrieves current weather information and a 5-day forecast for a specified location from the MSN Weather service.

### Signature
```javascript
find(options, callback)
```

### Parameters
#### options (object) - Required
Configuration object containing search and weather parameters.
- **search** (string) - Required - Location name (e.g., "San Francisco, CA") or ZIP code (e.g., "94103") to search for weather information.
- **degreeType** (string) - Optional - Default: 'F' - Temperature scale: 'F' for Fahrenheit or 'C' for Celsius.
- **lang** (string) - Optional - Default: 'en-US' - Language culture code for the response (e.g., 'en-US', 'de-DE').
- **timeout** (number) - Optional - Default: 10000 - HTTP request timeout in milliseconds.

#### callback (function) - Required
Callback function invoked with (err, result) parameters.

### Return Value
The callback receives two parameters:
- **err** (Error | string | null): Error object, error message string, or null if successful
- **result** (Array): Array of weather result objects, empty array if no locations found.

Each result object has this structure:
```javascript
{
  location: {
    name: string,
    zipcode: string,
    lat: string,
    long: string,
    timezone: string,
    alert: string,
    degreetype: string,
    imagerelativeurl: string
  },
  current: {
    temperature: string,
    skycode: string,
    skytext: string,
    date: string,
    observationtime: string,
    observationpoint: string,
    feelslike: string,
    humidity: string,
    winddisplay: string,
    day: string,
    shortday: string,
    windspeed: string,
    imageUrl: string
  } | null,
  forecast: Array<{
    low: string,
    high: string,
    skycodeday: string,
    skytextday: string,
    date: string,
    day: string,
    shortday: string,
    precip: string
  }> | null
}
```
```

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

### Accessing 5-Day Forecast Data

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Retrieves weather data for a specific location and then accesses and displays the 5-day forecast, including dates, temperature ranges (low/high), and daily conditions.

```javascript
weather.find({
  search: 'New York, NY',
  degreeType: 'F'
}, function(err, result) {
  if (err) return console.error(err);

  var weather = result[0];
  
  if (weather.forecast && weather.forecast.length > 0) {
    console.log('5-Day Forecast for ' + weather.location.name + ':');
    weather.forecast.forEach(function(day) {
      console.log(day.date + ' (' + day.day + '): ' + 
                  day.low + '-' + day.high + ', ' + 
                  day.skytextday);
    });
  }
});
```

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

### Main Function Signature

Source: https://github.com/devfacet/weather/blob/master/_autodocs/INDEX.md

The signature for the main 'find' function, outlining its parameters and callback.

```javascript
weather.find({search: string, degreeType?: string, lang?: string, timeout?: number}, callback)
```

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

### Simple Location Lookup

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Performs a basic weather lookup for a specified location and logs the current temperature.

```javascript
weather.find({
  search: 'New York, NY'
}, function(err, result) {
  if (err) return console.error(err);
  console.log(result[0].current.temperature);
});
```

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

### FindOptions

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Configuration object passed to the `find()` function to specify search parameters and behavior.

```APIDOC
## FindOptions

Configuration object passed to the `find()` function to specify search parameters and behavior.

### Fields

- **search** (string) - Required - Location name (e.g., "San Francisco, CA") or ZIP code to search for weather information. This value is URL-encoded before being sent to the weather service.
- **degreeType** (string) - Optional - Temperature scale indicator: 'F' for Fahrenheit or 'C' for Celsius. Defaults to 'F'.
- **lang** (string) - Optional - Language culture code for the API response. Defaults to 'en-US'. Examples: 'en-US', 'de-DE', 'fr-FR'.
- **timeout** (number) - Optional - HTTP request timeout in milliseconds. Defaults to 10000 (10 seconds).

### Used By
- [`weather.find()`](api-reference/find.md) — passed as first parameter (options)
```

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

### Timeout Handling for HTTP Requests

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Demonstrates how to set a timeout for the weather API request and handle potential timeout errors (ETIMEDOUT, ESOCKETTIMEDOUT).

```javascript
weather.find({
  search: 'London',
  timeout: 5000  // 5 second timeout
}, function(err, result) {
  if (err && err.code === 'ETIMEDOUT') {
    console.error('Weather service request timed out');
  }
});
```

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

### Default Module Values

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

These are the default values for language, temperature scale, and timeout defined within the module.

```javascript
defLang       = 'en-US'     // Default language culture code
defDegreeType = 'F'         // Default temperature scale (Fahrenheit)
defTimeout    = 10000       // Default timeout: 10 seconds (in milliseconds)
```

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

### FindOptions Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Configuration object for weather queries. 'search' is required. 'degreeType', 'lang', and 'timeout' are optional with default values.

```javascript
{
  search: string,           // Required
  degreeType?: 'F' | 'C',   // Default: 'F'
  lang?: string,            // Default: 'en-US'
  timeout?: number          // Default: 10000
}
```

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

### Weather Response Data Structure

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Illustrates the expected JSON structure for a weather data response, including location details, current conditions, and a 5-day forecast.

```json
{
  "location": {
    "name",
    "zipcode",
    "lat", "long",
    "timezone",
    "alert",
    "degreetype",
    "imagerelativeurl"
  },
  "current": {
    "temperature",
    "skycode",
    "skytext",
    "humidity",
    "windspeed",
    "// ... and more properties"
  },
  "forecast": [
    {
      "date",
      "low", "high",
      "skytextday",
      "precip"
      "// ... and more properties"
    }
    "// ... up to 5 days"
  ]
}
```

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

### Find Weather by City Name (Fahrenheit)

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Fetches current weather data for a specified city and state, returning results in Fahrenheit. Handles potential errors and cases where no locations are found.

```javascript
var weather = require('weather-js');

weather.find({
  search: 'San Francisco, CA',
  degreeType: 'F'
}, function(err, result) {
  if (err) {
    console.error('Weather lookup failed:', err);
    return;
  }

  if (result.length === 0) {
    console.log('No locations found');
    return;
  }

  var current = result[0];
  console.log('Location:', current.location.name);
  console.log('Temperature:', current.current.temperature + '°F');
  console.log('Conditions:', current.current.skytext);
});
```

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

### Find Weather by ZIP Code (Celsius)

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Searches for weather information using a ZIP code and specifies results in Celsius with English (US) language settings. Iterates through and logs the names of found locations.

```javascript
weather.find({
  search: '75001',
  degreeType: 'C',
  lang: 'en-US'
}, function(err, result) {
  if (err) {
    console.error('Error:', err);
    return;
  }

  result.forEach(function(locationData) {
    console.log(locationData.location.name);
  });
});
```

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

### Handle Missing Weather Data Structure in JavaScript

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this snippet when the service returns valid XML but lacks the expected `weatherdata.weather` structure. This often indicates an API change or version mismatch.

```javascript
weather.find({search: 'Berlin'}, function(err, result) {
  if (err && err.message === 'failed to parse weather data') {
    console.error('Weather service returned unexpected data structure');
    // Likely indicates service API change or version mismatch
  }
});
```

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

### Weather Search with Custom Timeout

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Sets a custom timeout for the weather search request, useful for slower network conditions.

```javascript
weather.find({
  search: 'London',
  timeout: 20000  // 20 second timeout
}, function(err, result) {
  // Waits longer for response
});
```

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

### Handle Missing Search Input Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle cases where the 'options.search' property is missing or empty.

```javascript
weather.find({degreeType: 'F'}, callback);  // Error: 'missing search input'
weather.find({search: ''}, callback);       // Error: 'missing search input'
weather.find({}, callback);                 // Error: 'missing search input'
```

```javascript
weather.find(options, function(err, result) {
  if (err === 'missing search input') {
    console.error('Location search term is required');
  }
});
```

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

### weather.find() Signature

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

This is the signature for the weather.find() method, indicating its parameters.

```javascript
find(options, callback)
```

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

### Handle Missing Weather Array in JavaScript

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Implement this to manage cases where the parsed XML is incomplete and does not contain the weather array, which could be due to malformed XML or missing forecast/current weather sections.

```javascript
weather.find({search: 'Miami'}, function(err, result) {
  if (err && err.message === 'missing weather info') {
    console.error('Weather data array is missing from response');
  }
});
```

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

### CurrentConditions

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Represents the current weather conditions for a location. This object includes temperature, sky conditions, date, time, humidity, wind information, and an image URL for the weather icon.

```APIDOC
## CurrentConditions

### Description
Current weather conditions for a location.

### Fields
- **temperature** (string) - Current temperature value (e.g., "70"). No unit suffix; use parent location's degreetype to determine Fahrenheit or Celsius.
- **skycode** (string) - Numeric code representing weather condition (e.g., "32" for Sunny, "26" for Cloudy). Used to construct weather icon URLs.
- **skytext** (string) - Human-readable weather condition (e.g., "Sunny", "Cloudy", "Thunderstorms").
- **date** (string) - Date of the observation in YYYY-MM-DD format (e.g., "2017-03-14").
- **observationtime** (string) - Time of observation in HH:MM:SS format (e.g., "13:15:00").
- **observationpoint** (string) - City/region name where the observation was taken (e.g., "San Francisco, California").
- **feelslike** (string) - "Feels like" temperature value accounting for wind and humidity.
- **humidity** (string) - Relative humidity percentage (e.g., "59"). No percent sign included.
- **winddisplay** (string) - Human-readable wind description (e.g., "3 mph West").
- **day** (string) - Full day name (e.g., "Tuesday").
- **shortday** (string) - Three-letter abbreviated day name (e.g., "Tue").
- **windspeed** (string) - Wind speed (e.g., "3 mph"). Includes unit.
- **imageUrl** (string) - Full URL to the weather condition icon. Automatically constructed from location.imagerelativeurl + 'law/' + skycode + '.gif'.

### Used By
- [WeatherResult](#weatherresult) — part of current field
```

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

### weather.find

Source: https://github.com/devfacet/weather/blob/master/_autodocs/INDEX.md

Finds weather information for a specified location. It accepts configuration options and returns results via a callback.

```APIDOC
## weather.find

### Description
Finds weather information for a specified location. It accepts configuration options and returns results via a callback.

### Method
Not explicitly defined, likely a JavaScript function call.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (object) - Required - Request configuration object.
  - **search** (string) - Required - Location name or ZIP code.
  - **degreeType** (string) - Optional - Temperature scale, default 'F' (Fahrenheit).
  - **lang** (string) - Optional - Language code, default 'en-US'.
  - **timeout** (number) - Optional - Request timeout in milliseconds, default 10000.
- **callback** (function) - Required - Callback function to handle the result or error.

### Request Example
```javascript
weather.find({ search: 'New York', degreeType: 'C' }, (err, data) => {
  if (err) {
    console.error(err);
  } else {
    console.log(data);
  }
});
```

### Response
#### Success Response
- **data** (object) - Location weather data. Structure includes `LocationInfo`, `CurrentConditions`, and `ForecastDay`.

#### Response Example
```json
{
  "location": {
    "name": "New York",
    "region": "NY",
    "country": "USA",
    "lat": "40.71",
    "lon": "-74.01",
    "tz_id": "America/New_York",
    "localtime": "2023-10-27 10:30"
  },
  "current": {
    "temp_c": "15",
    "temp_f": "59",
    "condition": {
      "text": "Partly cloudy",
      "code": 1003
    },
    "wind_mph": "10",
    "wind_kph": "16",
    "humidity": "60",
    "cloud": "50"
  },
  "forecast": [
    {
      "date": "2023-10-27",
      "day": {
        "maxtemp_c": "18",
        "mintemp_c": "10",
        "avgtemp_c": "14"
      },
      "astro": {
        "sunrise": "07:00",
        "sunset": "18:00"
      }
    }
  ]
}
```

### Errors
- 'invalid options'
- 'missing search input'
- Error('request failed')
- Error('failed to get body content')
- Error('invalid body content')
- Error (xml parse error)
- Error('failed to parse weather data')
- Error('missing weather info')
- Service error messages
- Network/timeout errors
```

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

### Access Weather Forecast

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Retrieve weather forecast data for a location and iterate through the daily forecast to log the date and day's sky condition. Ensure the 'forecast' property exists before accessing.

```javascript
weather.find({search: 'London'}, function(err, result) {
  if (err) return console.error(err);
  if (result[0].forecast) {
    result[0].forecast.forEach(function(day) {
      console.log(day.date + ': ' + day.skytextday);
    });
  }
});
```

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

### German Language Weather Interface

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Retrieves weather information with the interface and results in German.

```javascript
weather.find({
  search: 'Berlin',
  lang: 'de-DE'
}, function(err, result) {
  if (err) return console.error(err);
  console.log(result[0].current.skytext); // German condition text
});
```

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

### Celsius Search with German Language

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Configures the search to return temperature in Celsius and use German language settings for the response.

```javascript
weather.find({
  search: 'Berlin',
  degreeType: 'C',
  lang: 'de-DE'
}, function(err, result) {
  // Temperature in Celsius, German text
});
```

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

### ZIP Code Search with Spanish Interface

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Searches for weather using a ZIP code and configures the interface to use Spanish language and Celsius for temperature.

```javascript
weather.find({
  search: '28001',  // Madrid ZIP code
  degreeType: 'C',
  lang: 'es-ES'
}, function(err, result) {
  // Spanish weather terms and day names
});
```

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

### Internal Module IIFE Structure

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Demonstrates the module's internal architecture using an Immediately Invoked Function Expression (IIFE) to encapsulate private state and expose a public API.

```javascript
module.exports = (function() {
  // Private variables and functions
  var xmlParser = ...
  var find = function find(options, callback) { ... }
  
  // Public API
  return { find: find }
})()
```

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

### Handle Multiple Weather Results

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/module.md

Query weather data for a search term that may yield multiple locations and iterate through the results to log each location's name. Useful when the search term is ambiguous.

```javascript
weather.find({search: 'Washington'}, function(err, result) {
  if (err) return console.error(err);
  // result contains array of locations (Washington DC, Washington State, etc.)
  result.forEach(function(location) {
    console.log(location.location.name);
  });
});
```

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

### Handle Multiple Location Results

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Searches for a location that might have multiple results and iterates through them to log each location's name.

```javascript
weather.find({
  search: 'Washington'
}, function(err, result) {
  if (err) return console.error(err);
  // Multiple Washingtons found
  result.forEach(function(location) {
    console.log(location.location.name);
  });
});
```

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

### Handle Empty Response Body Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle cases where the HTTP response body is empty, null, or undefined.

```javascript
weather.find({search: 'Boston'}, function(err, result) {
  if (err && err.message === 'failed to get body content') {
    console.error('Response body is empty');
  }
});
```

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

### Handle Invalid Options Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle cases where the 'options' parameter is null or not an object.

```javascript
weather.find(null, callback);
           // Error: 'invalid options'
weather.find("search string", callback); // Error: 'invalid options'
weather.find(123, callback);             // Error: 'invalid options'
```

```javascript
weather.find({search: 'San Francisco'}, function(err, result) {
  if (err === 'invalid options') {
    console.error('Options must be an object');
  }
});
```

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

### FindOptions Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Configuration object for the `find()` function. Specify search parameters like location, temperature scale, language, and request timeout.

```typescript
{
  search: string,
  degreeType?: string,
  lang?: string,
  timeout?: number
}
```

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

### ForecastDay Type

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Represents a single day's forecast data, including temperature, sky conditions, date, and precipitation.

```APIDOC
## ForecastDay

A single day in the 5-day forecast.

```javascript
{
  low: string,
  high: string,
  skycodeday: string,
  skytextday: string,
  date: string,
  day: string,
  shortday: string,
  precip: string
}
```

| Field | Type | Description |
|-------|------|-------------|
| low | string | Forecasted low temperature (e.g., "52"). No unit suffix; use parent location's degreetype. |
| high | string | Forecasted high temperature (e.g., "69"). No unit suffix; use parent location's degreetype. |
| skycodeday | string | Numeric code for forecasted weather condition (e.g., "31" for Clear, "34" for Mostly Sunny). |
| skytextday | string | Human-readable forecasted weather condition (e.g., "Clear", "Mostly Sunny", "Cloudy"). |
| date | string | Date of the forecast in YYYY-MM-DD format (e.g., "2017-03-13"). |
| day | string | Full day name (e.g., "Monday"). |
| shortday | string | Three-letter abbreviated day name (e.g., "Mon"). |
| precip | string | Forecasted precipitation percentage (e.g., "10", "20"). Empty string if no precipitation data. No percent sign included. |

### Used By
- [WeatherResult](#weatherresult) — array items in forecast field
```

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

### XML Parser Configuration

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Configuration for the xml2js parser, specifying keys for character data and attributes, and enabling array wrapping.

```javascript
charkey: 'C$'      // Character node key in parsed JSON
attrkey: 'A$'      // Attribute key in parsed JSON
explicitArray: true // Force array wrapping for all elements
```

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

### Celsius Temperature with Custom Timeout

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Requests weather data in Celsius and specifies a custom request timeout duration.

```javascript
weather.find({
  search: 'Paris',
  degreeType: 'C',
  timeout: 20000
}, function(err, result) {
  if (err) return console.error(err);
  console.log(result[0].current.temperature + '°C');
});
```

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

### Weather Module

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

The main Weather Module object, providing access to weather querying functions.

```APIDOC
## Weather Module

The exported weather module object.

```javascript
{
  find: function(options, callback)
}
```

| Property | Type | Description |
|----------|------|-------------|
| find | Function | Query the weather service. See [`weather.find()`](api-reference/find.md) for full documentation. |

### Usage
```javascript
var weather = require('weather-js');
// weather.find() is available as the primary API
```
```

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

### Module Exports

Source: https://github.com/devfacet/weather/blob/master/_autodocs/INDEX.md

Defines the exported functions from the module. Currently, only the 'find' function is exported.

```javascript
module.exports = {
  find: function(options, callback)
}
```

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

### Find Weather Information

Source: https://github.com/devfacet/weather/blob/master/README.md

Use the weather.find method to search for weather information by location and degree type. Handles errors and logs the JSON result.

```javascript
var weather = require('weather-js');

// Options:
// search:     location name or zipcode
// degreeType: F or C

weather.find({search: 'San Francisco, CA', degreeType: 'F'}, function(err, result) {
  if(err) console.log(err);

  console.log(JSON.stringify(result, null, 2));
});
```

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

### CurrentConditions Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Defines the structure for current weather conditions at a location. Includes temperature, sky conditions, observation details, humidity, wind, and an image URL for weather icons.

```javascript
{
  temperature: string,
  skycode: string,
  skytext: string,
  date: string,
  observationtime: string,
  observationpoint: string,
  feelslike: string,
  humidity: string,
  winddisplay: string,
  day: string,
  shortday: string,
  windspeed: string,
  imageUrl: string
}
```

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

### Weather Module API Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Defines the exported weather module object with its primary 'find' function for querying weather data.

```javascript
{
  find: function(options, callback)
}
```

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

### General Error Handling Pattern

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

A recommended pattern for handling various error types, including string-based validation/service errors, Error objects, and unknown error types. It also checks for empty results.

```javascript
weather.find({search: location, degreeType: 'F'}, function(err, result) {
  // Check for any error type
  if (err) {
    // Handle string errors (validation, service errors)
    if (typeof err === 'string') {
      console.error('Validation or service error:', err);
      return;
    }
    
    // Handle Error objects
    if (err instanceof Error) {
      console.error('Request or parsing error:', err.message);
      return;
    }
    
    // Fallback for other error types
    console.error('Unknown error:', err);
    return;
  }
  
  // Check for empty result (location not found)
  if (result.length === 0) {
    console.log('No locations found');
    return;
  }
  
  // Process weather data
  console.log('Weather data retrieved successfully');
});
```

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

### weather.find() Result Object Structure

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Defines the structure of the result object returned by the weather.find() callback, including location, current weather, and forecast details.

```javascript
{
  location: {
    name: string,
    zipcode: string,
    lat: string,
    long: string,
    timezone: string,
    alert: string,
    degreetype: string,
    imagerelativeurl: string
  },
  current: {
    temperature: string,
    skycode: string,
    skytext: string,
    date: string,
    observationtime: string,
    observationpoint: string,
    feelslike: string,
    humidity: string,
    winddisplay: string,
    day: string,
    shortday: string,
    windspeed: string,
    imageUrl: string
  } | null,
  forecast: Array<{
    low: string,
    high: string,
    skycodeday: string,
    skytextday: string,
    date: string,
    day: string,
    shortday: string,
    precip: string
  }> | null
}
```

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

### Parse Numeric String Values to Integers

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Numeric values like temperature and humidity are returned as strings. Use parseInt() to convert them to numbers for calculations.

```javascript
var temp = parseInt(result[0].current.temperature);
var humidity = parseInt(result[0].current.humidity);
```

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

### Parse Coordinate String Values to Floats

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Latitude and longitude are provided as decimal strings. Use parseFloat() to convert them to floating-point numbers.

```javascript
var lat = parseFloat(result[0].location.lat);
var long = parseFloat(result[0].location.long);
```

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

### Find Weather with Custom Timeout

Source: https://github.com/devfacet/weather/blob/master/_autodocs/api-reference/find.md

Performs a weather search with a custom timeout duration (in milliseconds). This is useful for controlling how long the request will wait for a response before potentially failing.

```javascript
weather.find({
  search: 'Washington',
  degreeType: 'F',
  timeout: 15000
}, function(err, result) {
  if (err) {
    console.error('Error:', err);
    return;
  }

  console.log('Found ' + result.length + ' locations');
  
  result.forEach(function(location) {
    console.log('- ' + location.location.name);
    if (location.current) {
      console.log('  Feels like: ' + location.current.feelslike);
      console.log('  Humidity: ' + location.current.humidity + '%');
    }
  });
});
```

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

### ForecastDay Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Defines the structure for a single day's forecast data, including temperature, sky conditions, and date.

```javascript
{
  low: string,
  high: string,
  skycodeday: string,
  skytextday: string,
  date: string,
  day: string,
  shortday: string,
  precip: string
}
```

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

### Handle 'Not Found' as Empty Result

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

When a search query returns no matching locations, the API returns an empty array instead of an error. This behavior is consistent with v2.0.0 and later.

```javascript
callback(null, []);  // No error, empty result array
```

```javascript
weather.find({search: '.@@..xyz'}, function(err, result) {
  // err will be null
  // result will be [] (empty array)
  if (result.length === 0) {
    console.log('No locations found for this search');
  }
});
```

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

### LocationInfo

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Represents geographic and service metadata for a weather location. This object provides details such as name, zipcode, coordinates, timezone, alerts, temperature unit, and image URL base.

```APIDOC
## LocationInfo

### Description
Geographic and service metadata for a weather location.

### Fields
- **name** (string) - Display name of the location (e.g., "San Francisco, CA"). Returned as-is from the MSN Weather API.
- **zipcode** (string) - ZIP code for the location. May be empty string if not available.
- **lat** (string) - Latitude coordinate as a string. Example: "37.777".
- **long** (string) - Longitude coordinate as a string. Example: "-122.42".
- **timezone** (string) - Timezone offset as a string (e.g., "-7" for PDT, "-8" for PST).
- **alert** (string) - Weather alert message for the location. Empty string if no alert.
- **degreetype** (string) - Temperature unit in use: 'F' or 'C', matches the degreeType requested in [FindOptions](#findoptions).
- **imagerelativeurl** (string) - Base URL for weather icons (e.g., "http://blob.weather.microsoft.com/static/weather4/en-us/"). Used to construct full image URLs for weather conditions.

### Used By
- [WeatherResult](#weatherresult) — part of location field
```

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

### WeatherResult

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

A single weather result object containing location information, current conditions, and forecast data.

```APIDOC
## WeatherResult

A single weather result object containing location information, current conditions, and forecast data.

### Fields

- **location** ([LocationInfo](#locationinfo)) - Geographic and metadata information about the location. Always present.
- **current** ([CurrentConditions](#currentconditions) | null) - Current weather conditions. Null if not available from the API response.
- **forecast** (Array<[ForecastDay](#forecastday)> | null) - Array of 5-day forecast objects. Null if not available from the API response; may be empty array if forecast element exists but contains no days.

### Used By
- [`weather.find()`](api-reference/find.md) — returned in callback result array
```

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

### LocationInfo Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Defines the structure for geographic and service metadata for a weather location. Includes fields like name, zipcode, coordinates, timezone, alerts, degree type, and image URL.

```javascript
{
  name: string,
  zipcode: string,
  lat: string,
  long: string,
  timezone: string,
  alert: string,
  degreetype: string,
  imagerelativeurl: string
}
```

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

### Basic Weather Search

Source: https://github.com/devfacet/weather/blob/master/_autodocs/configuration.md

Performs a weather search using only the required 'search' option. It utilizes default settings for degree type, language, and timeout.

```javascript
var weather = require('weather-js');

weather.find({
  search: 'San Francisco, CA'
}, function(err, result) {
  // Uses defaults: degreeType='F', lang='en-US', timeout=10000
});
```

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

### WeatherResult Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/types.md

Represents a single weather result, containing location, current conditions, and forecast data. Current conditions and forecast may be null if unavailable.

```typescript
{
  location: LocationInfo,
  current: CurrentConditions | null,
  forecast: Array<ForecastDay> | null
}
```

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

### Handle HTTP Request Failed Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle errors related to HTTP request failures, such as non-200 status codes or network issues. It includes logic to extract the status code from the error message.

```javascript
weather.find({search: 'NYC'}, function(err, result) {
  if (err && err.message && err.message.indexOf('request failed') !== -1) {
    console.error('HTTP error occurred');
    // Extract status code from error message
    var match = err.message.match(/\((\d+)\)/);
    if (match) {
      var statusCode = parseInt(match[1]);
      console.error('Status code:', statusCode);
    }
  }
});
```

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

### Handle Service Error Messages in JavaScript

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Catch errors where the API returns a specific error message string, often due to invalid queries, rate limits, or other service-side issues. The error is expected to be a string.

```javascript
weather.find({search: 'invalid@#$%'}, function(err, result) {
  if (err && typeof err === 'string') {
    console.error('Service error:', err);
  }
});
```

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

### Handle Invalid Body Content Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle unexpected response formats where the body is not XML and does not contain 'not found'. This can indicate proxy issues or service misconfiguration.

```javascript
weather.find({search: 'Tokyo'}, function(err, result) {
  if (err && err.message === 'invalid body content') {
    console.error('Unexpected response format from weather service');
    // May indicate network proxy/firewall, DNS redirect, or service misconfiguration
  }
});
```

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

### Handle XML Parsing Failed Error

Source: https://github.com/devfacet/weather/blob/master/_autodocs/errors.md

Use this to handle errors that occur when the xml2js parser fails to parse the XML response body, which can be due to malformed XML or encoding issues.

```javascript
weather.find({search: 'Paris'}, function(err, result) {
  if (err && err.message && err.message.indexOf('Unexpected') !== -1) {
    console.error('XML parsing error:', err.message);
  }
});
```

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

### WeatherResult Type Definition

Source: https://github.com/devfacet/weather/blob/master/_autodocs/README.md

Represents the result for a single location's weather data, including location information, current conditions, and forecast.

```javascript
{
  location: LocationInfo,
  current: CurrentConditions | null,
  forecast: ForecastDay[] | null
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.