worldmet

https://openair-project.github.io/worldmet/
Admin
worldmet provides R tools to access and format surface meteorological observations from NOAA's...
Tokens:24,398
Snippets:219
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install development version of worldmet from GitHub

Source: https://openair-project.github.io/worldmet/index.html

Installs the development version of worldmet from GitHub using the pak package. The commented line installs pak if it is not already available.

```r
# install.packages("pak")
pak::pak("openair-project/worldmet")
```

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

### Example: Download NOAA station metadata

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations_live.html

Example wrapped in \dontrun to prevent execution during checks. Downloads all NOAA meta data and returns a tibble.

```r
if (FALSE) { # \dontrun{
meta <- import_isd_stations_live()
head(meta)
} # }
```

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

### Install worldmet from CRAN

Source: https://openair-project.github.io/worldmet/index.html

Installs the stable version of worldmet from CRAN.

```r
install.packages("worldmet")
```

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

### Example: import ISD hourly data with optional parallel processing

Source: https://openair-project.github.io/worldmet/reference/import_isd_hourly.html

Example usage of import_isd_hourly. The first call imports two years of data. The second call shows how to use mirai daemons for parallel processing when importing many years. This example is wrapped in \dontrun{}.

```R
if (FALSE) { # \dontrun{
# import some data
beijing_met <- import_isd_hourly(code = "545110-99999", year = 2010:2011)

# importing lots of data? use mirai for parallel processing
mirai::daemons(4)
beijing_met2 <- import_isd_hourly(code = "545110-99999", year = 2010:2025)
} # }
```

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

### Example: import and export data with write_adms()

Source: https://openair-project.github.io/worldmet/reference/write_adms.html

Example wrapped in \dontrun{} that imports hourly ISD data for 2012 and writes it to an ADMS file. The file path is '~/adms_met.MET'.

```r
if (FALSE) { # \dontrun{
# import some data then export it
dat <- import_isd_hourly(year = 2012)
write_adms(dat, file = "~/adms_met.MET")
} # }
```

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

### Configure parallel processing with mirai

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_monthly.html

Example of setting up mirai daemons to enable parallel processing for data import functions in worldmet.

```R
# set workers - once per session
mirai::daemons(4)

# import lots of data - NB: no change in the import function!
big_met <- import_ghcn_hourly(code = "UKI0000EGLL", year = 2010:2025)
```

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

### write_met() example usage

Source: https://openair-project.github.io/worldmet/reference/write_met.html

Example usage of write_met(). Imports hourly ISD data for 2012 and writes it to files. Wrapped in \dontrun{} so it is not executed during package checks.

```r
if (FALSE) { # \dontrun{
# import some data then export it
dat <- import_isd_hourly(year = 2012)
write_met(dat)
} # }
```

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

### Search for sites by name

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations.html

Example of searching for ISD sites using a specific name string.

```R
if (FALSE) { # \dontrun{
## search for sites with name beijing
getMeta(site = "beijing")
} # }
```

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

### Example: Importing Heathrow Lite Data

Source: https://openair-project.github.io/worldmet/reference/import_isd_lite.html

Example of using import_isd_lite to import data for Heathrow (code '037720-99999') for the year 2025. Wrapped in a dontrun block to prevent execution during package checks.

```R
if (FALSE) { # \dontrun{
heathrow_lite <- import_isd_lite(code = "037720-99999", year = 2025)
} # }
```

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

### import_isd_lite

Source: https://openair-project.github.io/worldmet/reference/import_isd_lite.html

Documentation for the import_isd_lite function, including usage, arguments, return value, details, parallel processing, and examples.

```APIDOC
## import_isd_lite

### Description
Imports "Lite" meteorological data from the NOAA Integrated Surface Database (ISD). This function provides a subset of the larger `importNOAA()` dataset featuring eight common climatological variables, with values assigned to the nearest measurement at the top of the hour.

### Usage
```r
import_isd_lite(
  code = "037720-99999",
  year = 2025,
  progress = rlang::is_interactive(),
  quiet = FALSE
)
```

### Arguments
- **code** (character) - Required - The identifying code as a character string. The code is a combination of the USAF and the WBAN unique identifiers, separated by a hyphen (e.g., `"037720-99999"`).
- **year** (numeric) - Required - The year to import. Can be a vector of years (e.g., `2000:2005`).
- **progress** (logical) - Optional - Show a progress bar when importing many stations/years? Defaults to `TRUE` in interactive R sessions. Passed to `.progress` in `purrr::map()` and/or `purrr::pmap()`.
- **quiet** (logical) - Optional - Print missing sites/years to the screen? Defaults to `FALSE`.

### Value
Returns a data frame of surface observations. The data frame is consistent for use with the `openair` package. Note that the data are returned in GMT (UTC) time zone format. Users may wish to express the data in other time zones, e.g., to merge with air pollution data.

### Details
Note the following units for the main variables:
- **date** - Date/time in POSIXct format. **Note the time zone is UTC and may need to be adjusted to merge with other local data.**
- **latitude** - Latitude in decimal degrees (-90 to 90).
- **longitude** - Longitude in decimal degrees (-180 to 180). Negative numbers are west of the Greenwich Meridian.
- **elev** - Elevation of site in metres.
- **ws** - Wind speed in m/s.
- **wd** - Wind direction in degrees. 90 is from the east.
- **air_temp** - Air temperature in degrees Celsius.
- **atmos_pres** - The sea level pressure in millibars.
- **dew_point** - The dew point temperature in degrees Celsius.
- **precip_6** - 6-hour precipitation in mm.
- **precip_1** - 1-hour precipitation in mm.
- **sky** - Sky Condition Total Coverage Code.

The data are returned in GMT (UTC). It may be necessary to adjust the time zone when combining with other data. For example, if air quality data were available for Beijing with time zone set to "Etc/GMT-8" (note the negative offset even though Beijing is ahead of GMT. See the `openair` package and manual for more details), then the time zone of the met data can be changed to be the same. One way of doing this would be `attr(met$date, "tzone") <- "Etc/GMT-8"` for a meteorological data frame called `met`. The two data sets could then be merged based on `date`.

### Parallel Processing
If you are importing a lot of meteorological data, this can take a long while. This is because each combination of year and station requires downloading a separate data file from NOAA's online data directory, and the time each download takes can quickly add up. Many data import functions in `{worldmet}` can use parallel processing to speed downloading up, powered by the capable `{mirai}` package. If users have any `{mirai}` "daemons" set, these functions will download files in parallel. The greatest benefits will be seen if you spawn as many daemons as you have cores on your machine, although one fewer than the available cores is often a good rule of thumb. Your mileage may vary, however, and naturally spawning more daemons than station-year combinations will lead to diminishing returns.

```r
# set workers - once per session
mirai::daemons(4)

# import lots of data - NB: no change in the import function!
big_met <- import_ghcn_hourly(code = "UKI0000EGLL", year = 2010:2025)
```

### See also
`getMeta()` to obtain the codes based on various site search approaches.
Other NOAA ISD functions: `import_isd_hourly()`, `import_isd_stations()`, `import_isd_stations_live()`

### Author
Jack Davison

### Examples
```r
if (FALSE) { # \dontrun{
heathrow_lite <- import_isd_lite(code = "037720-99999", year = 2025)
} # }
```
```

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

### Search for sites by coordinates

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations.html

Example of finding the nearest ISD stations to a specific latitude and longitude.

```R
if (FALSE) { # \dontrun{
## search for near a specified lat/lng - near Beijing airport
## returns 'n_max' nearest by default
getMeta(lat = 40, lng = 116.9)
} # }
```

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

### Access worldmet function documentation

Source: https://openair-project.github.io/worldmet/index.html

Opens the R documentation for the import_ghcn_stations function in the worldmet package.

```r
?worldmet::import_ghcn_stations
```

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

### Usage: import_isd_stations_live()

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations_live.html

Usage signature for the function. The ellipsis is currently unused.

```r
import_isd_stations_live(...)
```

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

### write_met(x, path, ext, delim, suffix, progress)

Source: https://openair-project.github.io/worldmet/reference/write_met.html

Writes a meteorological data frame to files, chunked by site and year. The data must be imported by `import_isd_hourly()`, `import_ghcn_hourly()`, or `import_ghcn_daily()`. Each station and year is written to a separate file in the specified directory.

```APIDOC
## write_met(x, path, ext, delim, suffix, progress)

### Description
Writes data returned by any of `import_isd_hourly()`, `import_ghcn_hourly()`, or `import_ghcn_daily()` to a file. Each station and year in the data is written to a separate file.

### Usage
```r
write_met(
  x,
  path = ".",
  ext = c("rds", "delim", "parquet"),
  delim = ",",
  suffix = "",
  progress = rlang::is_interactive()
)
```

### Arguments
- **x** (data frame) - Required - A data frame imported by `import_isd_hourly()`, `import_ghcn_hourly()`, or `import_ghcn_daily()`.
- **path** (string) - Optional - The path to a directory to save each file. By default, this is the working directory.
- **ext** (character) - Optional - The file type to use when saving the data. Can be `"rds"`, `"delim"` or `"parquet"`. Note that `"parquet"` requires the `arrow` package.
- **delim** (string) - Optional - Delimiter used to separate values when `ext = "delim"`. Must be a single character. Defaults to being comma-delimited (`","`).
- **suffix** (string) - Optional - An additional suffix to append to file names. Useful examples could be `"_isd"`, `"_hourly"`, `"_lite"`, and so on.
- **progress** (logical) - Optional - Show a progress bar when writing many stations/years? Defaults to `TRUE` in interactive R sessions. Passed to `.progress` in `purrr::walk()`.

### Value
`write_met()` returns `path` invisibly.

### Examples
```r
if (FALSE) { # \dontrun{
# import some data then export it
dat <- import_isd_hourly(year = 2012)
write_met(dat)
} # }
```
```

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

### View weatherCodes data frame

Source: https://openair-project.github.io/worldmet/reference/weatherCodes.html

The `weatherCodes` data frame contains weather description codes used in the ISD. The example shows the first 10 rows of the 100-row tibble, with columns `pwc` (weather code) and `description`. The `pwc` column can be merged with the `pwc` column in `importNOAA()` datasets.

```r
weatherCodes
```

```r
weatherCodes
#> # A tibble: 100 × 2
#>    pwc   description                                       
#>    <chr> <chr>                                             
#>  1 00    clear skies                                       
#>  2 01    clouds dissolving                                 
#>  3 02    state of sky unchanged                            
#>  4 03    clouds developing                                 
#>  5 04    visibility reduced by smoke                       
#>  6 05    smoke                                             
#>  7 06    widespread dust in suspension not raised by wind  
#>  8 07    dust or sand raised by wind                       
#>  9 08    well developed dust or sand whirls                
#> 10 09    dust or sand storm within sight but not at station
#> # ℹ 90 more rows
```

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

### Import GHCN station inventory with import_ghcn_inventory()

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_inventory.html

Function signature for importing GHCN station inventory. The database argument selects between hourly (GHCNh) and daily (GHCNd) inventories. The pivot argument applies only to the hourly inventory, allowing wide or long formats. The progress argument defaults to TRUE in interactive R sessions and is passed to readr::read_fwf() and/or purrr::pmap().

```r
import_ghcn_inventory(
  database = c("hourly", "daily"),
  pivot = c("wide", "long"),
  progress = rlang::is_interactive()
)
```

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

### import_ghcn_monthly_temp()

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_monthly.html

Imports monthly average temperature data from the GHCN monthly database. Allows selection of the table (inventory or data) and the dataset version (qcu, qcf, or qfe).

```APIDOC
## import_ghcn_monthly_temp()

### Description
Imports monthly average temperature data from the GHCN monthly database. Allows selection of the table (inventory or data) and the dataset version (qcu, qcf, or qfe).

### Usage
```r
import_ghcn_monthly_temp(
  table = c("inventory", "data"),
  dataset = c("qcu", "qcf", "qfe")
)
```

### Arguments
- **table** (character) - Required - Either `"inventory"`, `"data"`, or both. The tables to read and return in the output list.
- **dataset** (character) - Required - One of the following options:
  - `"qcu"`: Quality Control, Unadjusted
  - `"qcf"`: Quality Control, Adjusted, using the Pairwise Homogeneity Algorithm.
  - `"qfe"`: Quality Control, Adjusted, Estimated using the Pairwise Homogeneity Algorithm. Only the years 1961-2010 are provided. This is to help maximize station coverage when calculating normals.

### Value
A list of tibbles.

### Parallel Processing
If importing a lot of meteorological data, this can take a long while. If users have any `{mirai}` "daemons" set, these functions will download files in parallel.

### See Also
Other GHCN functions: `import_ghcn_countries()`, `import_ghcn_daily()`, `import_ghcn_hourly()`, `import_ghcn_inventory()`, `import_ghcn_stations()`

### Author
Jack Davison
```

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

### import_ghcn_inventory(database, pivot, progress)

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_inventory.html

Imports a data inventory of GHCN stations from the NOAA database, revealing the earliest and latest years of data available for each station. The function supports both hourly and daily databases with configurable output format and progress indication.

```APIDOC
## import_ghcn_inventory(database, pivot, progress)

### Description
This function accesses a data inventory of GHCN stations available through either the GHCNh or GHCNd. The returned data.frame contains data which reveals the earliest and latest years of data available for each station from the NOAA database.

### Usage
```r
import_ghcn_inventory(
  database = c("hourly", "daily"),
  pivot = c("wide", "long"),
  progress = rlang::is_interactive()
)
```

### Arguments
- **database** (character) - Required - One of "hourly" or "daily", which defines whether to import the GHCNh or GHCNd inventory. The way in which these files is formatted is different.
- **pivot** (character) - Required - One of "wide" or "long". The GHCNh inventory can be returned in a "wide" format (with id, year and twelve month columns) or a "long" format (with id, year, month, and count columns). Does not apply to the GHCNd inventory.
- **progress** (logical) - Optional - The inventory file is large and can be slow to download. Show a progress indicator when accessing the inventory? Defaults to TRUE in interactive R sessions. Passed to progress in readr::read_fwf() and/or purrr::pmap().

### Value
a tibble

### See also
Other GHCN functions: import_ghcn_countries(), import_ghcn_daily(), import_ghcn_hourly(), import_ghcn_monthly_temp(), import_ghcn_stations()

### Author
Jack Davison
```

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

### import_isd_stations_live()

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations_live.html

Downloads all NOAA station metadata and returns it as a tibble. This function is useful for obtaining a complete list of stations for direct querying or re-use.

```APIDOC
## import_isd_stations_live()

### Description
Downloads all NOAA meta data, allowing for re-use and direct querying.

### Usage
```r
import_isd_stations_live(...)
```

### Arguments
- `...` - Currently unused.

### Value
A tibble containing station metadata.

### See also
Other NOAA ISD functions: `import_isd_hourly()`, `import_isd_lite()`, `import_isd_stations()`

### Examples
```r
if (FALSE) { # \dontrun{
meta <- import_isd_stations_live()
head(meta)
} # }
```
```

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

### import_ghcn_monthly_prcp()

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_monthly.html

Imports monthly precipitation data from the GHCN monthly database. Allows selection of specific stations, years, and tables, with an optional progress bar.

```APIDOC
## import_ghcn_monthly_prcp()

### Description
Imports monthly precipitation data from the GHCN monthly database. Allows selection of specific stations, years, and tables, with an optional progress bar.

### Usage
```r
import_ghcn_monthly_prcp(
  station = NULL,
  year = NULL,
  table = c("inventory", "data"),
  progress = rlang::is_interactive()
)
```

### Arguments
- **station** (character) - Optional - The specific stations to import monthly precipitation data for.
- **year** (numeric) - Optional - One or more years of interest. If `NULL`, the default, all years of data available for the chosen `station`s will be imported. Note that, in the GHCNd and GHCNm, files are split by station but not year, so setting a `year` will not speed up the download. Specifying fewer years will improve the speed of a GHCNh download, however.
- **table** (character) - Required - Either `"inventory"`, `"data"`, or both. The tables to read and return in the output list.
- **progress** (logical) - Optional - Show a progress bar when importing many stations? Defaults to `TRUE` in interactive R sessions. Passed to `.progress` in `purrr::map()`.

### Value
A list of tibbles.

### Parallel Processing
If importing a lot of meteorological data, this can take a long while. If users have any `{mirai}` "daemons" set, these functions will download files in parallel.

### See Also
Other GHCN functions: `import_ghcn_countries()`, `import_ghcn_daily()`, `import_ghcn_hourly()`, `import_ghcn_inventory()`, `import_ghcn_stations()`

### Author
Jack Davison
```

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

### Usage of import_ghcn_monthly_temp and import_ghcn_monthly_prcp

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_monthly.html

Functions to access monthly temperature and precipitation summaries from the GHCN database.

```R
import_ghcn_monthly_temp(
  table = c("inventory", "data"),
  dataset = c("qcu", "qcf", "qfe")
)

import_ghcn_monthly_prcp(
  station = NULL,
  year = NULL,
  table = c("inventory", "data"),
  progress = rlang::is_interactive()
)
```

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

### import_ghcn_daily()

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_daily.html

Imports meteorological data from the GHCNd database for one or more stations. Users can specify years, choose data format, control extra columns, append codes, and show progress.

```APIDOC
## import_ghcn_daily()

### Description
Imports meteorological data from the GHCNd database for one or more stations. Users can specify years, choose data format, control extra columns, append codes, and show progress.

### Usage
```r
import_ghcn_daily(
  station,
  year = NULL,
  source = c("csv"),
  extra = FALSE,
  append_codes = FALSE,
  codes = c("measurement_flag", "quality_flag", "source_flag"),
  progress = rlang::is_interactive()
)
```

### Arguments
- **station** (character) - Required - One or more site codes for the station(s) of interest, obtained using `import_ghcn_stations()`.
- **year** (numeric) - Optional - One or more years of interest. If `NULL`, the default, all years of data available for the chosen `station`s will be imported. Note that, in the GHCNd and GHCNm, files are split by station but not year, so setting a `year` will not speed up the download. Specifying fewer years will improve the speed of a GHCNh download, however.
- **source** (character) - Optional - The data format for the GHCNd. Currently only `"csv"` is supported. This argument is included for future use.
- **extra** (logical) - Optional - Should additional columns be returned? The default, `FALSE`, returns an opinionated selection of elements that'll be of most interest to most users. `TRUE` will return everything available.
- **append_codes** (logical) - Optional - Logical. Should various codes and flags be appended to the output dataframe?
- **codes** (character) - Optional - When `append_codes` is `TRUE`, which codes should be appended to the dataframe? Any combination of `"measurement_flag"`, `"quality_flag"`, and/or `"source_flag"`.
- **progress** (logical) - Optional - Show a progress bar when importing many stations/years? Defaults to `TRUE` in interactive R sessions. Passed to `.progress` in `purrr::map()` and/or `purrr::pmap()`.

### Details
This function flexibly accesses meteorological data from the GHCNd database. Users can provide any of stations, and control whether attribute codes are returned with the data.

```

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

### import_ghcn_stations()

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_stations.html

Imports station metadata for the Global Historical Climatology Network (GHCN). Users can filter by name, country, state, or coordinates, and choose between hourly or daily databases. The return type can be a table, an sf object, or an interactive map.

```APIDOC
## import_ghcn_stations()

### Description
Imports station metadata for the Global Historical Climatology Network (GHCN). This function accesses a full list of GHCN stations available through either the GHCNh or GHCNd. As well as the station `id`, needed for importing measurement data, useful geographic and network metadata is also returned.

### Usage
```r
import_ghcn_stations(
  name = NULL,
  country = NULL,
  state = NULL,
  lat = NULL,
  lng = NULL,
  crs = 4326,
  n_max = 10L,
  provider = c(`Street Map` = "OpenStreetMap", Satellite = "Esri.WorldImagery"),
  database = c("hourly", "daily"),
  return = c("table", "sf", "map")
)
```

### Arguments
- **name** (character) - Optional - String value to filter metadata for specific site names. Searched as a sub-string case insensitively.
- **country** (character) - Optional - String value to filter metadata for specific countries. Matched exactly to codes accessed using `import_ghcn_countries()`.
- **state** (character) - Optional - String value to filter metadata for specific states. Matched exactly to codes accessed using `import_ghcn_countries()`.
- **lat** (numeric) - Optional - Decimal latitude (or other Y coordinate if using a different `crs`). If provided, the `n_max` closest stations to this coordinate will be returned.
- **lng** (numeric) - Optional - Decimal longitude (or other X coordinate if using a different `crs`). If provided, the `n_max` closest stations to this coordinate will be returned.
- **crs** (numeric) - Optional - Coordinate reference system (CRS) of the data, passed to `sf::st_crs()`. Default is EPSG:4326. Non-lat/lng coordinate systems will be re-projected to EPSG:4326 for comparisons with NOAA metadata.
- **n_max** (integer) - Optional - Number of closest stations to return when `lat` and `lng` are provided. Default is 10L.
- **provider** (character) - Optional - Base map provider when `return = "map"`. Default is a named vector allowing toggling between OpenStreetMap and Esri.WorldImagery. See http://leaflet-extras.github.io/leaflet-providers/preview/ for available base maps.
- **database** (character) - Optional - One of "hourly" or "daily", defining whether to import stations from GHCNh or GHCNd. Default is c("hourly", "daily").
- **return** (character) - Optional - Type of R object to import data as. One of "table", "sf", or "map". Default is c("table", "sf", "map").

### Value
One of:
- a tibble (when `return = "table"`)
- an sf object (when `return = "sf"`)
- an interactive `leaflet` map (when `return = "map"`)

### See Also
Other GHCN functions: `import_ghcn_countries()`, `import_ghcn_daily()`, `import_ghcn_hourly()`, `import_ghcn_inventory()`, `import_ghcn_monthly_temp()`

### Author
Jack Davison
```

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

### import_ghcn_hourly(station, year, source, hourly, extra, abbr_names, append_codes, codes, progress)

Source: https://openair-project.github.io/worldmet/reference/import_ghcn_hourly.html

Imports meteorological data from the GHCNh database. Users can specify stations and years, control data flag codes, and choose abbreviated column names.

```APIDOC
## import_ghcn_hourly

### Description
Imports meteorological data from the GHCNh database. Users can provide any number of years and stations, and fully control the sorts of data flag codes that are returned. By default, column names are shortened for easier use in R, but longer, more descriptive names can be requested.

### Usage
```r
import_ghcn_hourly(
  station = "UKI0000EGLL",
  year = NULL,
  source = c("psv", "parquet"),
  hourly = TRUE,
  extra = FALSE,
  abbr_names = TRUE,
  append_codes = FALSE,
  codes = c("measurement_code", "quality_code", "report_type", "source_code",
    "source_id"),
  progress = rlang::is_interactive()
)
```

### Arguments
- **station** (character) - Required - One or more site codes for the station(s) of interest, obtained using `import_ghcn_stations()`.
- **year** (numeric or integer) - Optional - One or more years of interest. If `NULL` (default), all years of data available for the chosen `station`s will be imported.
- **source** (character) - Optional - Two identical data formats to read from: `"psv"` (flat, pipe-delimited files) and `"parquet"` (newer, faster, columnar format). The latter requires the `arrow` package as an additional dependency. Only applies when `year` is not `NULL`.
- **hourly** (logical) - Optional - Should hourly means be calculated? Default is `TRUE`. If `FALSE`, raw data (possibly sub-hourly) are returned.
- **extra** (logical) - Optional - Should additional columns be returned? Default is `FALSE`, returning an opinionated selection of elements. `TRUE` returns everything available.
- **abbr_names** (logical) - Optional - Should column names be abbreviated? When `TRUE` (default), columns like `"wind_direction"` are shortened to `"wd"`. When `FALSE`, names match raw data but in lower case.
- **append_codes** (logical) - Optional - Should various codes and flags be appended to the output dataframe?
- **codes** (character) - Optional - When `append_codes` is `TRUE`, which codes to append? Any combination of `"measurement_code"`, `"quality_code"`, `"report_type"`, `"source_code"`, and/or `"source_id"`.
- **progress** (logical) - Optional - Show a progress bar when importing many stations/years? Defaults to `TRUE` in interactive R sessions. Passed to `.progress` in `purrr::map()` and/or `purrr::pmap()`.

### Return Value
A data frame containing the requested meteorological data with columns depending on the arguments used.
```

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

### import_isd_stations()

Source: https://openair-project.github.io/worldmet/reference/import_isd_stations.html

Search ISD station metadata by site name, country, state, or coordinates. Returns a data frame (or sf object or leaflet map) with station details including a code for use with import_isd_hourly().

```APIDOC
## import_isd_stations()

### Description
Search the Integrated Surface Database (ISD) station metadata to find a site code for use with import_isd_hourly(). Searches can be performed by site name, country, state, or nearest locations based on latitude and longitude.

### Usage
```r
import_isd_stations(
  site = NULL,
  country = NULL,
  state = NULL,
  lat = NULL,
  lng = NULL,
  crs = 4326,
  n_max = 10,
  end_year = "current",
  provider = c(`Street Map` = "OpenStreetMap", Satellite = "Esri.WorldImagery"),
  return = c("table", "sf", "map")
)
```

### Arguments
- **site** (character) - Optional - A site name search string, e.g. `site = "heathrow"`. Partial and case-insensitive matches are allowed.
- **country** (character) - Optional - Two-letter country code. See https://www.ncei.noaa.gov/pub/data/noaa/isd-history.csv for a full listing.
- **state** (character) - Optional - Two-letter state code.
- **lat** (numeric) - Optional - Decimal latitude (or Y coordinate if using a different CRS).
- **lng** (numeric) - Optional - Decimal longitude (or X coordinate if using a different CRS).
- **n_max** (numeric) - Optional - Number of closest stations to return when lat/lng are provided. Default is 10.
- **crs** (numeric) - Optional - Coordinate reference system of the data, passed to sf::st_crs(). Default is EPSG:4326. Non-lat/lng CRS will be re-projected to EPSG:4326 for comparison with NOAA metadata.
- **end_year** (character/numeric) - Optional - Filter sites based on data end year. Can be "current", "any", a numeric year (e.g., 2016), or a range (e.g., 1990:2016). By default, only sites with data for the current year are returned.
- **provider** (character) - Optional - Base map provider when return = "map". Default is a named vector with OpenStreetMap and Esri.WorldImagery. See http://leaflet-extras.github.io/leaflet-providers/preview/ for available options.
- **return** (character) - Optional - Type of R object to return: "table" (data.frame), "sf" (spatial data.frame), or "map" (interactive leaflet map). Default is "table".

### Value
A data frame with all available metadata, including a `code` column that can be supplied to importNOAA(). If lat/lng searches are made, an approximate distance `dist` in km is also returned.

### Examples
```r
if (FALSE) { # \dontrun{
## search for sites with name beijing
import_isd_stations(site = "beijing")
} # }

if (FALSE) { # \dontrun{
## search for near a specified lat/lng - near Beijing airport
## returns 'n_max' nearest by default
import_isd_stations(lat = 40, lng = 116.9)
} # }
```
```
Tokens:
Raw