Package: metget
MetGet is an application which allows users to query, format, and blend meteorological data from various sources
to be used in hydrodynamic modeling applications.Development PartnersMetGet is developed byThe Water Instituteand has been funded by the
University of North Carolina at Chapel HillCoastal Resilience Center of Excellence.MetGet Client ApplicationThe MetGet client application is a tool that allows you to interact with the MetGet server. It may be used
as a traditional command line tool or theMetGetBuildRestclass may be imported and run in a custom application.The MetGet client handles the interaction with the server via RESTful API calls and downloading output
data from S3 buckets. The client application is not a requirement for using MetGet, but it is a convenient
way to interact with the server.MetGet Server AccessThemetgetclient application interacts with an instance of ametget-server,
which is a Kubernetes application that archives, builds, and provides to users meteorological data through the client application.
The client does not require that you use any specific MetGet server instance. Instead, you may choose to operate your ownmetget-serverinstance or you maycontactThe Water Institute to request access to
an available instance.InstallationThe MetGet client application can be installed using from the PyPi repository. The below commands show how to install the client and its dependencies.$pip3installmetgetTerminologyThere are several terms used in the MetGet client application that are important to understand. The below list of terms
aims to explain these terms and why they are available as options in the client application.analysis- The term analysis is synonymous with the term "nowcast". It is the time when the model is initialized, or the "zero" hour of a model run. Requesting that MetGet provide "analysis" data via the--analysiscommand line option will fore MetGet to return only zero hour for any forecast runs. This option is incompatible with "--multiple-forecasts" and "--initialization-skip".multiple-forecasts- This option is used to signify that the user wants to request multiple forecast hours from the model. This allows MetGet to string together different forecasts to create quasi-hindcast data. The selection of available data is done by selecting unique times with the smallest offset from the start of their respective forecasts. This option is incompatible with--analysis.initialization-skip- In some instances, it may be useful to skip the first [n] hours of a particular forecast when there is a potentially severe initialization that occurs in the atmospheric model. This option instructs MetGet to ignore the first [n] hours of a forecast.Environment VariablesThere are three influential environment variables which can be set as a convenience to the user. These variables are:METGET_API_KEY- The API key used to authenticate with MetGetMETGET_ENDPOINT- The URL of the MetGet server, i.e.https://metget.server.orgMETGET_API_VERSION- The version of the MetGet API to use. The system will default to1and unless you are using the Kubernetes based MetGet deployment, the version 1 api is appropriate.UsageThe client application can request multiple types of data from the server. The below examples show how to request
data from a MetGet server instance via the command line tool.Note: In the below examples, we assume that the above environment variables have been set. If they have not been set,
you will need to pass additional command line flags.Example 1 - Request GFS dataThis example requests data from the GFS for a two-day period. We will generate the data from a single self-consistent forecast
formatted as a single NetCDF file. The data will be interpolated to a 0.25 degree grid and cover a portion of the Gulf of Mexico.$metgetbuild--domaingfs0.25-10010-8030\--start"2023-06-01 00:00"\--end"2023-06-03 00:00"\--timestep3600\--outputmetget_gfs_data.nc\--formatgeneric-netcdfExample 2 - Request GFS data with multiple forecastsThis example requests data from the GFS for a thirty-day period. We will generate the data from multiple forecasts as a
quasi-hindcast. The data will be interpolated to a 0.25 degree grid and cover a portion of the Gulf of Mexico.$metgetbuild--domaingfs0.25-10010-8030\--start"2023-05-01 00:00"\--end"2023-06-01 00:00"\--outputmetget_gfs_data.nc\--formatgeneric-netcdf\--timestep3600\--multiple-forecastsExample 3 - Request GFS data with multiple forecasts and initialization skipThis example requests data from the GFS for a thirty-day period. We will generate the data from multiple forecasts as a
quasi-hindcast. The data will be interpolated to a 0.25 degree grid and cover a portion of the Gulf of Mexico. We will
skip the first 6 hours of each forecast.$metgetbuild--domaingfs0.25-10010-8030\--start"2023-05-01 00:00"\--end"2023-06-01 00:00"\--timestep3600\--formatgeneric-netcdf\--multiple-forecasts\--initialization-skip6\--outputmetget_gfs_data.ncExample 4 - Request HWRF data overlaid on GFS dataThis example requests data from the HWRF model (Hurricane Mawar) with background forcing from the GFS model. Note that at the present time,
the output format must support multi-domain data. Currently, the only format that supports this isowi-ascii. The
data will be interpolated to a 0.25 degree grid and cover a portion of the Gulf of Mexico.$metgetbuild--domainhwrf-mawar02w0.15-9020-8525\--domaingfs0.25-10010-8030\--start"2023-06-01 00:00"\--end"2023-06-03 00:00"\--timestep3600\--backfill\--formatowi-ascii\--outputmetget_hwrf_dataExample 5 - Get the status of the GFS model runsThis example demonstrates the ability for the system to provide information about what data is currently available$metgetstatusgfs--formatpretty
Statusformodel:GFS(class:synoptic)+---------------------+---------------------+------------------+|ForecastCycle|EndTime|Status|+---------------------+---------------------+------------------+|2023-07-0618:00:00|2023-07-1709:00:00|incomplete(255)||2023-07-0612:00:00|2023-07-2212:00:00|complete||2023-07-0606:00:00|2023-07-2206:00:00|complete||2023-07-0600:00:00|2023-07-2200:00:00|complete||2023-07-0518:00:00|2023-07-2118:00:00|complete||2023-07-0512:00:00|2023-07-2112:00:00|complete||2023-07-0506:00:00|2023-07-2106:00:00|complete||2023-07-0500:00:00|2023-07-2100:00:00|complete||2023-07-0418:00:00|2023-07-2018:00:00|complete||2023-07-0412:00:00|2023-07-2012:00:00|complete||2023-07-0406:00:00|2023-07-2006:00:00|complete||2023-07-0400:00:00|2023-07-2000:00:00|complete|+---------------------+---------------------+------------------+Example 6: Retrieve GEOJSON track data for a specific stormThis example demonstrates the ability to retrieve track data for a specific storm. The track data is returned in GEOJSON format.$metgettrack--year2022--storm9--basinal--typeforecast--advisory3#...Hurricane Ian 2022, Advisory 3 track data$metgettrack--year2022--storm9--basinal--typebesttrack#...Hurricane Ian 2022, best track dataCustom ApplicationsThe MetGet client library (MetGetBuildRest) can be imported and used in custom applications. The below example shows how to use the
client application in a custom Python script. Below is a simple version of how the main client application interacts with themetget-clientlibrary.
You can use this as a starting point for your own custom applications.importargparsefrommetget.metget_buildimportMetGetBuildRestmetget_server="https://metget.server.org"metget_api_key="my-api-key"metget_api_version=2args=argparse.Namespaceoutput_format='owi-ascii'# ...Building the requestrequest_data=MetGetBuildRest.generate_request_json(analysis=args.analysis,multiple_forecasts=args.multiple_forecasts,start_date=args.start,end_date=args.end,format=output_format,data_type=args.variable,backfill=args.backfill,time_step=args.timestep,domains=MetGetBuildRest.parse_command_line_domains(args.domain,args.initialization_skip),compression=args.compression,epsg=args.epsg,filename=args.output,strict=args.strict,dry_run=args.dryrun,save_json_request=args.save_json_request,)client=MetGetBuildRest(metget_server,metget_api_key,metget_api_version)data_id,status_code=client.make_metget_request(request_data)client.download_metget_data(data_id,args.check_interval,args.max_wait,)