# Resolve radio context from explicit coordinates

Private, no-store context. Precise location is never included in the result. POST accepts at most 512 UTF-8 bytes. Provider failures produce unknown weather/holiday values. No automatic retries.

Operation: getPreciseRadioContext
POST /api/radio/context

Access: anonymous. Automatic retries: none. Redirects: manual. Request body limit: 512 bytes.
Default timeout: 30 seconds. Response limit: 16 MiB. Pagination is opt-in and bounded; an exhausted bound reports incomplete execution.

[HTML reference](/developers/api/getPreciseRadioContext) · [Authoritative schemas](/api/openapi.json)

## Wire contract

```json
{
  "operationId": "getPreciseRadioContext",
  "summary": "Resolve radio context from explicit coordinates",
  "description": "Private, no-store context. Precise location is never included in the result. POST accepts at most 512 UTF-8 bytes. Provider failures produce unknown weather/holiday values. No automatic retries.",
  "tags": [
    "radio"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "timezone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          },
          "required": [
            "latitude",
            "longitude",
            "timezone"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Local clock, season, weather and holiday context",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Vary": {
          "schema": {
            "const": "CF-IPCountry"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "locationLabel": {
                "type": "string"
              },
              "timezone": {
                "type": "string"
              },
              "localDate": {
                "type": "string"
              },
              "localTime": {
                "type": "string"
              },
              "timeOfDay": {
                "type": "string",
                "enum": [
                  "dawn",
                  "morning",
                  "afternoon",
                  "evening",
                  "night"
                ]
              },
              "season": {
                "type": "string",
                "enum": [
                  "spring",
                  "summer",
                  "autumn",
                  "winter",
                  "unknown"
                ]
              },
              "daylight": {
                "type": "string",
                "enum": [
                  "day",
                  "night",
                  "unknown"
                ]
              },
              "weekday": {
                "type": "string"
              },
              "isWeekday": {
                "type": "boolean"
              },
              "holiday": {
                "type": "object",
                "properties": {
                  "isHoliday": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "isHoliday",
                  "name"
                ],
                "additionalProperties": false
              },
              "weather": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "clear",
                      "cloudy",
                      "fog",
                      "drizzle",
                      "rain",
                      "snow",
                      "storm",
                      "unknown"
                    ]
                  },
                  "description": {
                    "type": "string"
                  },
                  "temperatureC": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "apparentTemperatureC": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "isDay": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  }
                },
                "required": [
                  "kind",
                  "description",
                  "temperatureC",
                  "apparentTemperatureC",
                  "isDay"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "locationLabel",
              "timezone",
              "localDate",
              "localTime",
              "timeOfDay",
              "weekday",
              "isWeekday",
              "holiday",
              "weather"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "400": {
      "description": "Invalid location request",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "413": {
      "description": "Location request exceeds 512 bytes",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    }
  }
}
```

## Synthetic examples

### curl

```bash
curl --fail-with-body --max-time 30 --max-filesize 16777216 --request POST 'https://irvinebroque.com/api/radio/context' --header 'Accept: application/json' --header 'Content-Type: application/json' --data-binary @request.json
```

### TypeScript

```typescript
import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.radio.preciseContext({
  "body": {
    "latitude": 0,
    "longitude": 0,
    "timezone": "UTC"
  }
});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.
```

### CLI

```bash
irvinebroque radio precise-context --body-file request.json
```

### request.json

```json
{
  "latitude": 0,
  "longitude": 0,
  "timezone": "UTC"
}
```