# Build with Notamify API

Use this file as a beginner-friendly implementation brief for building an app with the Notamify Active NOTAMs API.

Before writing code, read the current Notamify API documentation and follow it as the source of truth.

## First, Check What the User Wants

This guide is for building an app or integration on the Notamify API.

If the user only wants answers about NOTAMs, such as "what is closed at EGLL tomorrow?", do not build an app. Use the Notamify MCP tools if they are already connected. Otherwise, with a shell, install the `notamify` command line and its agent skill, then follow the skill:

```bash
uv tool install notamify      # or: pipx install notamify
notamify skill install        # for Claude Code; use --dir for other agents' skills directories
```

Chat apps without a shell can connect to the hosted MCP server at `https://mcp.notamify.com/mcp`.

## Target Outcome

Build a working Active NOTAMs lookup that:

- Helps the user start Notamify Pro and get an API key.
- Keeps the API key server-side.
- Fetches Active NOTAMs for one airport first.
- Displays readable Notamify interpretation fields.
- Handles empty, error, and missing-configuration states clearly.

## Agent Runbook

Follow this order. Do not jump straight to UI code.

### Step 0: Read the Docs

Open the current Notamify docs before implementing:

- Quick start: https://skymerse.gitbook.io/notamify-api/basics/quick-start
- Authentication guide: https://skymerse.gitbook.io/notamify-api/basics/authentication-guide
- Active NOTAMs endpoint: https://skymerse.gitbook.io/notamify-api/active-notams-endpoint
- Credits and costs: https://skymerse.gitbook.io/notamify-api/basics/notamify-api-credits-and-costs

If MCP tools are available, use `searchDocumentation` and `getPage` to read the full current pages.

### Step 1: Confirm Account Setup

Tell the user they need:

- Notamify Pro.
- The 7 day free trial if they are new.
- The 50 included starter API credits.
- An API key from https://notamify.com/api-manager.

If they do not have Notamify Pro yet, send them to https://notamify.com/activate-pro before building API calls.

### Step 2: Set the API Key

Ask the user for their Notamify API key when needed, or guide them to add it to their local environment. Recommend:

```bash
NOTAMIFY_API_KEY=their_api_key_here
```

Keep the key out of frontend code, browser bundles, and Git.

### Step 3: Verify the API Before Building UI

Run or ask the user to run a tiny server-side test first:

```bash
curl --request GET \
  --url "https://api.notamify.com/api/v2/notams?location=EPWA&per_page=5" \
  --header "Authorization: Bearer $NOTAMIFY_API_KEY"
```

Expected result: HTTP 200 with JSON containing `notams`, `total_count`, `page`, and `per_page`.

If you have a shell, the `notamify` command line runs the same check and reports problems with stable exit codes. It reads the key from `NOTAMIFY_TOKEN`, not `NOTAMIFY_API_KEY`:

```bash
uv tool install notamify
export NOTAMIFY_TOKEN="$NOTAMIFY_API_KEY"
notamify notams active EPWA --json
```

Exit code `3` means the key is missing or was rejected. Exit code `5` means the account has no API access or no credits left. Each check like this costs 1 credit, so run it once, not repeatedly.

If this fails:

- `401`: check the key and bearer header.
- `403`: check Notamify Pro subscription or API entitlement.
- Empty `notams`: this can be valid. Try another airport or date window.
- Network or `5xx`: retry later and show a user-friendly error.

### Step 4: Build the Smallest Useful App

Start with one airport lookup. Add multiple airports, filters, pagination, and detail views only after the first request path works.

### Step 5: Verify the App

Before finishing, verify:

- The app loads with no API key and shows a setup/configuration message.
- The app can fetch one airport, for example `EPWA`.
- Empty results render as an empty state, not a crash.
- API errors do not reveal the API key.
- The browser never receives the Notamify API key.

## What the User Needs First

Guide the user through these requirements before implementing:

1. They need a Notamify account.
2. They need an active Notamify Pro subscription. Notamify Pro includes a 7 day free trial and 50 API credits to start. If they do not have Pro yet, they can get it at https://notamify.com/activate-pro.
3. They need a Notamify API key from the API Manager.
4. The API key must be stored in a server-side environment variable.

Useful links:

- Start Notamify Pro: https://notamify.com/activate-pro
- API Manager: https://notamify.com/api-manager
- API docs: https://skymerse.gitbook.io/notamify-api
- API docs (MCP access): https://skymerse.gitbook.io/notamify-api/~gitbook/mcp
- Python SDK and `notamify` command line: https://github.com/skymerse/notamify-sdk-python

Ask the user for the key when needed, or ask them to add it to their local environment and tell you the variable name. Use:

```bash
NOTAMIFY_API_KEY=their_api_key_here
```

Then ask which environment variable name they used, for example `NOTAMIFY_API_KEY`.

## API Key Setup for Non-Technical Users

Explain that the API key is a private credential for the app. It is okay to ask the user for it when configuring the project, but the finished app must read it from a server-side environment variable and must not expose it in browser code, logs, screenshots, or Git.

Guide the user through this flow:

1. Start Notamify Pro at https://notamify.com/activate-pro if they do not have it yet. New users can use the 7 day free trial and 50 starter API credits.
2. Open https://notamify.com/api-manager.
3. Create or reveal an API key.
4. Store it as a secret environment variable named `NOTAMIFY_API_KEY`.

For a local project, help the user add this line to a `.env` file in the project root:

```bash
NOTAMIFY_API_KEY=paste_the_api_key_here
```

If terminal commands help, keep them simple:

```bash
cd /path/to/their/project
touch .env
open .env
```

After `.env` is saved, restart the app and test the key:

```bash
cd /path/to/their/project
source .env
curl --request GET \
  --url "https://api.notamify.com/api/v2/notams?location=EPWA&per_page=5" \
  --header "Authorization: Bearer $NOTAMIFY_API_KEY"
```

For a deployed app, ask the user to add the same value in the hosting platform's Environment Variables or Secrets settings:

- Variable name: `NOTAMIFY_API_KEY`
- Variable value: their Notamify API key

Use `process.env.NOTAMIFY_API_KEY` or the platform equivalent from backend code only. If the user is unsure where to add it, ask which tool or platform they are using and guide them there.

## Documentation Workflow for Agents

If your environment supports MCP, connect to:

```text
https://skymerse.gitbook.io/notamify-api/~gitbook/mcp
```

Use:

- `searchDocumentation` to find current Notamify API docs.
- `getPage` to fetch the full markdown page before implementing.

Start with these docs pages:

- Quick start: https://skymerse.gitbook.io/notamify-api/basics/quick-start
- Authentication guide: https://skymerse.gitbook.io/notamify-api/basics/authentication-guide
- Active NOTAMs endpoint: https://skymerse.gitbook.io/notamify-api/active-notams-endpoint
- Credits and costs: https://skymerse.gitbook.io/notamify-api/basics/notamify-api-credits-and-costs

Do not invent endpoint fields. Fetch and follow the current docs.

To see the real response shape before writing parsing code, the `notamify` command line can print it. With `NOTAMIFY_TOKEN` set as in Step 3, `--dry-run --auth api-key` shows the exact REST request URL without sending it or spending a credit. The second command fetches one real page for 1 credit, and `--fields` keeps its output small:

```bash
notamify notams active EPWA --dry-run --auth api-key
notamify notams active EPWA --json --fields id,notam_number,starts_at,ends_at,interpretation.excerpt
```

Ask the user before running any command that may cost more than one credit. The command line stops such commands with exit code `4` and prints the exact command to rerun with `--yes` once the user agrees.

## Beginner Scope

For a first Notamify API app, use only Active NOTAMs:

```http
GET https://api.notamify.com/api/v2/notams
```

Stay on the Active NOTAMs endpoint unless the user explicitly asks for advanced endpoints later.

If the user is new, build something simple first:

- Airport NOTAM lookup.
- Current NOTAM dashboard for one airport.
- Multi-airport NOTAM list.
- Search or filter by category, Q-code, or affected element.
- A readable airport status page using Notamify interpretation fields.

## Authentication

Notamify uses bearer token authentication. The OpenAPI docs declare HTTP bearer auth; standard HTTP clients usually send:

```http
Authorization: Bearer YOUR_API_KEY
```

Verify the current authentication docs before shipping.

Important security rules:

- Call Notamify from backend code only.
- Never expose the API key in frontend JavaScript.
- Never commit the API key to source control.
- Never log the API key.
- Never put the key into screenshots or public error messages.
- In a frontend app, create a backend route or server action that calls Notamify.

## Active NOTAMs Basics

Base URL:

```text
https://api.notamify.com/api/v2
```

Endpoint:

```http
GET /notams
```

Full URL example:

```text
https://api.notamify.com/api/v2/notams?location=EPWA
```

What this endpoint returns:

- Active or currently relevant NOTAM data for requested locations.
- Original NOTAM text.
- Notamify AI interpretation fields.
- Parsed affected elements.
- Parsed schedules.
- Map elements and GeoJSON when available.
- Pagination metadata.

Cost:

- Active NOTAMs cost 1 API credit per page.
- New Notamify Pro subscribers get 50 API credits to start.

## First Request

Use one airport first. After that works, add more options.

```bash
curl --request GET \
  --url "https://api.notamify.com/api/v2/notams?location=EPWA&per_page=30" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

In app code, replace `YOUR_API_KEY` with a server-side environment variable.

## Query Parameters for Active NOTAMs

Start with these:

- `location`: airport or location code. Example: `EPWA`.
- `page`: page number. Defaults to 1.
- `per_page`: number of NOTAMs per page. Defaults to 30 and is capped at 30.

Then add these when useful:

- `starts_at`: UTC ISO datetime for the start of the query window.
- `ends_at`: UTC ISO datetime for the end of the query window.
- `qcode`: filter by NOTAM Q-code, for example `QMRLC`.
- `category`: filter by Notamify interpretation category.
- `subcategory`: filter by Notamify interpretation subcategory.
- `affected_element`: filter by affected element effect or type.
- `excluded_classifications`: exclude `DOM`, `FDC`, `INTL`, or `MIL`.
- `notam_ids`: fetch specific NOTAM IDs.

Important limits:

- Use up to 5 locations per Active NOTAMs call.
- Use repeated query params for multiple locations: `?location=EPWA&location=EGLL`.
- `per_page` is capped at 30.
- `ends_at` must be later than `starts_at`.
- Use UTC ISO datetimes, for example `2026-05-06T00:00:00Z`.
- The active endpoint cannot start earlier than one day before current UTC datetime.

Example with two airports:

```text
https://api.notamify.com/api/v2/notams?location=EPWA&location=EGLL&page=1&per_page=30
```

Example with a date window:

```text
https://api.notamify.com/api/v2/notams?location=EPWA&starts_at=2026-05-06T00:00:00Z&ends_at=2026-05-06T23:59:00Z
```

## Response Shape

Active NOTAMs returns a paginated list:

```json
{
  "notams": [],
  "total_count": 0,
  "page": 1,
  "per_page": 30
}
```

Important NOTAM fields:

- `id`: Notamify UUID.
- `notam_number`: NOTAM identifier.
- `location`: location designator.
- `icao_code`: ICAO code when available.
- `classification`: `DOM`, `FDC`, `INTL`, or `MIL` when available.
- `starts_at`: NOTAM validity start.
- `ends_at`: NOTAM validity end.
- `issued_at`: when the NOTAM was issued.
- `is_estimated`: whether the end time is estimated.
- `is_permanent`: whether the NOTAM is permanent.
- `message`: readable NOTAM message.
- `icao_message`: original ICAO formatted NOTAM text.
- `qcode`: raw Q-code.
- `interpretation`: Notamify interpretation object.

Useful interpretation fields:

- `interpretation.excerpt`: short summary for cards and tables.
- `interpretation.description`: longer user-facing explanation.
- `interpretation.category`: top-level category.
- `interpretation.subcategory`: more specific category.
- `interpretation.affected_elements`: structured affected objects and operational effects.
- `interpretation.schedules`: parsed timing, including human-readable descriptions and RRULEs.
- `interpretation.schedule_description`: schedule summary when present.
- `interpretation.map_elements`: geometry and GeoJSON when available.

## What to Show in a Beginner App

For each NOTAM card or table row, show:

- NOTAM number.
- Airport or location.
- Start and end time.
- Short interpretation excerpt.
- Category or subcategory.
- Affected element chips if present.

In a detail view, show:

- Full interpretation description.
- Original ICAO message.
- Schedule description and RRULE data if present.
- Affected elements with type, identifier, effect, and details.
- Map geometry if `map_elements` includes GeoJSON.

Use Notamify interpretation fields for the main user experience. Keep the raw ICAO message available for traceability.

## JavaScript or TypeScript Backend Example

Use this only in backend code.

```ts
const NOTAMIFY_BASE_URL = "https://api.notamify.com/api/v2";

async function getActiveNotams(location: string) {
  const token = process.env.NOTAMIFY_API_KEY;

  if (!token) {
    throw new Error("Missing NOTAMIFY_API_KEY. Add a Notamify API key from https://notamify.com/api-manager.");
  }

  const params = new URLSearchParams();
  params.append("location", location.toUpperCase());
  params.set("page", "1");
  params.set("per_page", "30");

  const response = await fetch(`${NOTAMIFY_BASE_URL}/notams?${params}`, {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    const text = await response.text();
    throw new Error(`Notamify API request failed (${response.status}): ${text}`);
  }

  return response.json();
}
```

If building a Next.js app, put this in a route handler or server action, not in a client component.

## Python SDK Example

Install:

```bash
pip install notamify-sdk
```

Use:

```python
import os
from notamify_sdk import NotamifyClient, ActiveNotamsQuery

token = os.environ.get("NOTAMIFY_API_KEY")
if not token:
    raise RuntimeError("Missing NOTAMIFY_API_KEY. Generate a key at https://notamify.com/api-manager.")

client = NotamifyClient(token=token)
query = ActiveNotamsQuery(location=["EPWA"])

for notam in client.notams.active(query):
    print(notam.notam_number, notam.interpretation.excerpt)
```

## Error Handling

Handle these cases clearly:

- Missing environment variable: tell the user to create a Notamify API key in API Manager and store it server-side.
- No Notamify Pro subscription: tell the user they need Notamify Pro, which includes a 7 day free trial and 50 API credits to start, and send them to https://notamify.com/activate-pro.
- `401`: invalid or missing API key.
- `403`: account does not have access, subscription is missing, or entitlement is unavailable.
- `404`: no NOTAMs or no data for the request, depending on the endpoint response.
- `429`: rate limit or quota pressure.
- `5xx`: temporary API or network failure.
- Empty `notams`: valid empty state. Show "No active NOTAMs found" instead of an error.

Never show the raw API key in an error message.

## Common Pitfalls to Avoid

- Do not build the Notamify request in a client component or browser-only script.
- Do not continue with API implementation until the user has Notamify Pro or a trial and an API key.
- Do not assume `page=1` contains all results. Use pagination.
- Do not ask for more than 5 locations in one Active NOTAMs request.
- Do not use IATA locations. Acceptable are ICAO or FAA codes.
- Do not use local browser time for API windows. Convert to UTC ISO datetimes.
- Do not treat an empty `notams` array as a failure.
- Do not rely only on raw NOTAM text when interpretation fields are available.
- Do not move to advanced Notamify endpoints until the Active NOTAMs flow is working.

## Beginner Implementation Checklist

1. Explain that the user needs Notamify Pro, the 7 day free trial, and 50 starter API credits.
2. Direct the user to create an API key in API Manager.
3. Ask which environment variable stores the API key.
4. Verify the API with a tiny server-side request before building UI.
5. Build a server-side Notamify client helper.
6. Implement Active NOTAMs lookup for one airport first.
7. Add validation for 3 or 4 character location codes.
8. Add pagination using `page` and `per_page`.
9. Add loading, empty, and error states.
10. Display interpretation summaries first.
11. Keep original `icao_message` available in details.
12. Test with one airport, for example `EPWA`.

## Suggested First Task

If the user does not provide another goal, suggest building a simple Active NOTAMs lookup first. Ask only for the app requirements, the airport or airport list, and the environment variable name that stores the Notamify API key.