# Florida Man API

A free, open-source dataset of 10,000+ real Florida Man news headlines, accessible as a static JSON API hosted on GitHub Pages. No API key required.

---

## Base URL

```
https://juliayxhuang.github.io/florida-man-api
```

---

## Endpoints

### Get all headlines
```
GET /api/headlines.json
```

### Get headlines by date
```
GET /api/{MM}/{DD}.json
```
**Example** — April 23rd:
```
https://juliayxhuang.github.io/florida-man-api/api/04/23.json
```

### Get all headlines for a month
```
GET /api/{MM}/index.json
```
**Example** — all of April:
```
https://juliayxhuang.github.io/florida-man-api/api/04/index.json
```

### Get date index
Returns a list of all available dates and total headline count.
```
GET /api/index.json
```

---

## Response Format

Each headline object contains:

```json
{
  "title":    "Florida man arrested for alleged 1993 Bronx double murder",
  "url":      "https://www.foxnews.com/...",
  "source":   "foxnews.com",
  "date":     "2026-04-23",
  "keywords": ["florida", "arrested", "murder", "cold", "case"]
}
```

| Field | Type | Description |
|---|---|---|
| `title` | string | Full headline text |
| `url` | string | Link to original article |
| `source` | string | Domain of the news source |
| `date` | string | Publication date (YYYY-MM-DD) |
| `keywords` | array | Extracted keywords from the headline |
| `image` | string | (Optional) Article thumbnail image URL |

---

## Usage Example

```js
const response = await fetch(
  'https://juliayxhuang.github.io/florida-man-api/api/04/23.json'
);
const headlines = await response.json();
console.log(headlines[0].title);
```

---

## Details

- **10,000+ headlines** scraped from real news sources
- **No authentication** required — completely open access
- **CORS enabled** via GitHub Pages
- Updated occasionally as new headlines are collected
- Dates range from recent years through present

---

## Build / Update

This repo serves a static API from the generated `api/` folder (committed to GitHub for GitHub Pages).

When you update `headlines.json`, rebuild the API:

```sh
rm -rf api && python3 build_api.py
```

By default, the generated API excludes `image` to keep responses smaller and avoid hotlinking thumbnails. To include it, set `INCLUDE_IMAGES = True` in `build_api.py` and rebuild.

---

## Notes

- Some dates may have multiple headlines, others may have none
- Headlines are real news articles — not all follow the classic "Florida Man" comedy format; some cover serious topics
- This dataset is intended for personal, educational, and non-commercial use

---

## Contributing

Found a bug or want to contribute? Open an issue or pull request.

---

## Author

Made by [Julia](https://github.com/juliayxhuang) as part of an academic project at Parsons School of Design.

---

## License

[MIT](LICENSE) — free to use, just give credit.