# Castles API
> Castles around the world as an API — 17,000+ castles from Wikidata with their country, geographic coordinates and the year they were built. Search and filter castles by name, country and build-year range, or find every castle near any coordinate by great-circle distance (perfect for "castles near me" features). Spanning Germany, Italy, France, Spain, the UK and 100+ countries, it is ideal for travel, tourism, maps, history, education and trivia apps. Open data from Wikidata.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/castles-api/..."
```

## Pricing
- **Free** (Free) — 3,850 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 51,000 calls/Mo, 8 req/s
- **Pro** ($13/Mo) — 247,000 calls/Mo, 20 req/s
- **Mega** ($35/Mo) — 1,215,000 calls/Mo, 50 req/s

## Endpoints

### Castles

#### `GET /v1/nearby` — Castles near a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `50.11`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `8.68`
- `radius_km` (query, optional, string) — Search radius in km (0.5-1000, default 25)
- `limit` (query, optional, string) — Max results (1-100, default 20)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/castles-api/v1/nearby?lat=50.11&lon=8.68"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "total": 33,
        "center": {
            "lat": 50.11,
            "lon": 8.68
        },
        "results": [
            {
                "name": "Stalburger Oede",
                "country": "Germany",
                "latitude": 50.1266,
                "longitude": 8.68358,
                "built_year": null,
                "distance_km": 1.86
            },
            {
                "name": "Bornburg",
                "country": "Germany",
                "latitude": 50.13013,
                "longitude": 8.70499,
                "built_year": null,
                "distance_km": 2.86
            },
            {
                "name": "Fleschenburg",
                "country": "Germany",
                "latitude": 50.1018,
                "longitude": 8.73089,
                "built_year": null,
                "distance_km": 3.74
            },
            {
                "name": "Burg Rödelheim",
                "country": "Germany",
                "latitude": 50.1219,
                "longitude": 8.61238,
                "built_year": null,
                "distance_km": 5
            },
            {
                "name": "Burg Bachberg",
                "country": "Germany",
                "latitude": 50.1574,
                "longitude": 8.68788,
                "built_year": null,
                "distance_km": 5.3
            },
            {
                "name": "Burg Philippseck",
            
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search & filter castles

**Parameters:**
- `q` (query, optional, string) — Search by castle name
- `country` (query, optional, string) — Country, e.g. Germany, France Example: `Germany`
- `year_from` (query, optional, string) — Built in or after this year
- `year_to` (query, optional, string) — Built in or before this year
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/castles-api/v1/search?country=Germany&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "total": 3557,
        "offset": 0,
        "filters": {
            "q": null,
            "country": "Germany",
            "year_to": null,
            "year_from": null
        },
        "results": [
            {
                "name": "\"Felsenkeller, Bierkeller Burg Cadolzburg\"",
                "country": "Germany",
                "latitude": 49.45895,
                "longitude": 10.85175,
                "built_year": null
            },
            {
                "name": "Abenberg Castle",
                "country": "Germany",
                "latitude": 49.24333,
                "longitude": 10.96324,
                "built_year": null
            },
            {
                "name": "Abschnittsbefestigung Kirchberg",
                "country": "Germany",
                "latitude": 48.98983,
                "longitude": 11.30814,
                "built_year": null
            },
            {
                "name": "Abschnittsbefestigung Mallburg",
                "country": "Germany",
                "latitude": 48.9734,
                "longitude": 11.30602,
                "built_year": null
            },
            {
                "name": "Abschnittsbefestigung Puch",
                "country": "Germany",
                "latitude": 48.1808,
                "longitude": 11.2172,
                "built_year": null
            },
            {
                "name": "Abschnittsbe
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & top countries

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/castles-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Castles worldwide with country, coordinates and year built. Search by name, country and build-year range; /v1/nearby finds castles near a coordinate by great-circle distance.",
        "total": 17727,
        "fields": [
            "name",
            "country",
            "latitude",
            "longitude",
            "built_year"
        ],
        "source": "Wikidata (castles)",
        "countries": 102,
        "with_year": 2921,
        "top_countries": [
            {
                "count": 3557,
                "country": "Germany"
            },
            {
                "count": 2815,
                "country": "Italy"
            },
            {
                "count": 2640,
                "country": "France"
            },
            {
                "count": 2329,
                "country": "Spain"
            },
            {
                "count": 1801,
                "country": "United Kingdom"
            },
            {
                "count": 497,
                "country": "Turkey"
            },
            {
                "count": 423,
                "country": "Poland"
            },
            {
                "count": 421,
                "country": "Iran"
            },
            {
                "count": 375,
                "country": "Ireland"
            },
            {
                "count": 372,
                "country": "Switzerland"
            },
            {
                "c
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/castles-api
OpenAPI spec: https://www.oanor.com/api/castles-api/openapi.json