# Third-Party Setup Guide (Server Deployment)

Use this guide when deploying this API to a new server/environment.

Goal: make Weather API and Reverse Geolocation API work by setting required third-party keys.

---

## What you must set up

This project requires 2 third-party providers:

1. **Visual Crossing** (weather data)
2. **LocationIQ** (reverse geolocation: lat/lon -> place label)

If keys are missing, endpoints will fail.

---

## 1) Create provider accounts and keys

## A. Visual Crossing (Weather)

1. Create account at Visual Crossing Weather.
2. Generate/copy an API key.
3. Keep this key as: `VISUAL_CROSSING_API_KEY`.

## B. LocationIQ (Reverse Geolocation)

1. Create account at LocationIQ.
2. Generate/copy an API key.
3. Keep this key as: `LOCATIONIQ_API_KEY`.

---

## 2) Configure keys on server

This code supports key lookup in this order:

- First: environment variable
- Second: PHP constant in config file

### Recommended (production)

Set environment variables:

- `VISUAL_CROSSING_API_KEY`
- `LOCATIONIQ_API_KEY`

### Alternative (current project style)

Set constants in config (example: `config/local/config.php`):

- `define("VISUAL_CROSSING_API_KEY", "...");`
- `define("LOCATIONIQ_API_KEY", "...");`

Do not commit real production keys to git.

---

## 3) Endpoints that use these keys

## Weather endpoint

- Route: `GET /api/weather.php`
- Uses: `VISUAL_CROSSING_API_KEY`
- Required query params: `lat`, `lon`

### Test command

```bash
curl "http://<your-api-host>/api/weather.php?lat=-25.7479&lon=28.2293"
```

Expected: JSON weather payload (or provider response JSON).

## Reverse geolocation endpoint

- Route: `GET /api/reverse_geocode.php`
- Uses: `LOCATIONIQ_API_KEY`
- Required query params: `lat`, `lon`

### Test command

```bash
curl "http://<your-api-host>/api/reverse_geocode.php?lat=-25.7479&lon=28.2293"
```

Expected:

```json
{
  "label": "City, State"
}
```

---

## 4) Quick troubleshooting

## Weather API errors

- `500 Weather service not configured` -> set `VISUAL_CROSSING_API_KEY`
- `400 Invalid coordinates` -> check `lat`/`lon` ranges
- `502 Failed to fetch weather data` -> upstream/network/provider issue

## Reverse geolocation errors

- `503 Geocoding service not configured` -> set `LOCATIONIQ_API_KEY`
- `400 Invalid coordinates` -> check `lat`/`lon` ranges
- `502 Geocoding service error/failed` -> upstream/network/provider issue

---

## 5) Deployment checklist (third-party only)

- [ ] Visual Crossing account created and active
- [ ] LocationIQ account created and active
- [ ] Keys generated
- [ ] Keys configured on server (env vars preferred)
- [ ] Weather endpoint curl test passed
- [ ] Reverse geocode endpoint curl test passed
- [ ] Keys stored securely (not hardcoded in committed files for prod)