# parseMetarTime

Industry: Aviation

:::caution[Unreleased]
Not in `@northguild/gmt` 1.21.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
parseMetarTime(value: string, referenceInstant: string): string
```

Parse a METAR report-time group as an ISO 8601 UTC instant, read against a reference instant.

- **What it reads.** The `YYGGggZ` group that opens a METAR, a SPECI and a TAF's issue time: day of month, hour and minute in UTC, then `Z` with no space (`251200Z`). Upper-case `Z` only, ASCII digits only. Day 01–31, hour 00–23, minute 00–59; `24` is not read.
- **A reference is required.** The group has no month or year, and the function never uses "now": a stored report reads the same every month. Pass the time the report was received, or the archive's timestamp.
- **How the month is chosen** (GMT rule; WMO-No. 306 gives the day, hour and minute only). The result is the nearer, in exact elapsed time, of the latest candidate at or before the reference and the earliest after it. A month that lacks the day (31 in a 30-day month, 29 to 31 in February) is skipped. Of two equally near candidates the earlier wins. There is no distance limit; check staleness with `spanNs`.
- **UTC throughout.** Months are counted in UTC whatever the reference's offset, and the result always ends in `Z`. No local wall time is resolved, so no disambiguation policy applies.
- **Sources.** WMO-No. 306 FM 15 reg. 15.3.1 and 15.3.2 (METAR, SPECI), FM 51 reg. 51.1.2 (TAF issue time) and the symbolic letters `YY` and `GGggZ`. ICAO Annex 3 Appendix 3 was not reached.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | A METAR time group, `YYGGggZ` (e.g. "251200Z") |
| `referenceInstant` | `string` | An ISO 8601 instant with `Z` or an offset: the time the report was received or the archive's timestamp |

## Returns

the ISO instant ("2024-06-25T12:00:00Z"), or "" on invalid input

## Examples

```ts
import { parseMetarTime } from "@northguild/gmt/aviation/parse";

parseMetarTime("251200Z", "2024-06-25T12:20:00Z") // "2024-06-25T12:00:00Z"
```

## Source

[aviation/parse/parseMetarTime.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/aviation/parse/parseMetarTime.ts)
