search_city

Find a city in the app's database by name (any of the app's six languages works) and get its coordinates, IANA timezone and elevation — feed those into the other tools.

Parameters1

query

string

required

City name, e.g. 'Madrid', 'London', 'Nueva York'

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "City name, e.g. 'Madrid', 'London', 'Nueva York'"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_sun_times

Sunrise, sunset, solar noon, civil dawn/dusk, morning AND evening golden hour, and day length (with day-over-day trend) for a location and date. Handles midnight sun and polar night. Pure sun times — for vitamin D questions use the vitamin_d tools instead.

Parameters4

lat	number	required	Latitude in decimal degrees
lon	number	required	Longitude in decimal degrees
date	string	optional	Date as YYYY-MM-DD; defaults to today
timezone	string	optional	IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date as YYYY-MM-DD; defaults to today"
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC"
    }
  },
  "required": [
    "lat",
    "lon"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_vitamin_d_window

The solar vitamin D synthesis window for ONE specific day at a location, for a personal profile: when UV is strong enough (index ≥ 3), the best hour, the clear-sky minutes needed to reach the target IU, and (with atTime) the minutes at the specific hour the user plans to go out. Returns synthesisPossible=false when the sun never gets high enough that day. Only for single-day questions — for months, seasons or 'when during the year', call get_vitamin_d_year instead of calling this once per date.

Parameters10

lat	number	required	Latitude in decimal degrees
lon	number	required	Longitude in decimal degrees
date	string	optional	Date as YYYY-MM-DD; defaults to today
timezone	string	optional	IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC
skinType	integer	optional	Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3
exposedSkinFraction	number	optional	Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit
age	number	optional	Age in years (synthesis declines with age); omit for adult baseline
targetIU	number	optional	Vitamin D target per session in IU; default 1000
elevationM	number	optional	Ground elevation in metres (UV rises ~8%/km); default sea level
atTime	string	optional	Local HH:MM the user plans to go out — adds minutesNeeded and UV at that exact time

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date as YYYY-MM-DD; defaults to today"
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC"
    },
    "skinType": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "description": "Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3"
    },
    "exposedSkinFraction": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "description": "Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 120,
      "description": "Age in years (synthesis declines with age); omit for adult baseline"
    },
    "targetIU": {
      "type": "number",
      "minimum": 100,
      "maximum": 10000,
      "description": "Vitamin D target per session in IU; default 1000"
    },
    "elevationM": {
      "type": "number",
      "minimum": -100,
      "maximum": 6000,
      "description": "Ground elevation in metres (UV rises ~8%/km); default sea level"
    },
    "atTime": {
      "type": "string",
      "pattern": "^\\d{1,2}:\\d{2}$",
      "description": "Local HH:MM the user plans to go out — adds minutesNeeded and UV at that exact time"
    }
  },
  "required": [
    "lat",
    "lon"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_vitamin_d_year

The WHOLE YEAR of solar vitamin D for a location in a single call. monthsWithSun lists every month with at least one viable day (season edges count as partial months, see byMonth[].viableDays); solidMonths lists months where most days work; exactViableSpan gives the exact season boundaries; summary carries per-year aggregates for comparing places. Use this for any question about months, seasons, winter/summer or 'when during the year can I…' — never probe individual dates with get_vitamin_d_window for that.

Parameters8

lat	number	required	Latitude in decimal degrees
lon	number	required	Longitude in decimal degrees
timezone	string	optional	IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC
skinType	integer	optional	Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3
exposedSkinFraction	number	optional	Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit
age	number	optional	Age in years (synthesis declines with age); omit for adult baseline
targetIU	number	optional	Vitamin D target per session in IU; default 1000
elevationM	number	optional	Ground elevation in metres (UV rises ~8%/km); default sea level

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees"
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC"
    },
    "skinType": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "description": "Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3"
    },
    "exposedSkinFraction": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "description": "Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 120,
      "description": "Age in years (synthesis declines with age); omit for adult baseline"
    },
    "targetIU": {
      "type": "number",
      "minimum": 100,
      "maximum": 10000,
      "description": "Vitamin D target per session in IU; default 1000"
    },
    "elevationM": {
      "type": "number",
      "minimum": -100,
      "maximum": 6000,
      "description": "Ground elevation in metres (UV rises ~8%/km); default sea level"
    }
  },
  "required": [
    "lat",
    "lon"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_current_status

Whether RIGHT NOW is a good moment for vitamin D synthesis at a location, using live Open-Meteo UV/cloud data when reachable (clear-sky model otherwise): current UV index, minutes needed now, and when today's window opens or closes.

Parameters8

lat	number	required	Latitude in decimal degrees
lon	number	required	Longitude in decimal degrees
timezone	string	optional	IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC
skinType	integer	optional	Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3
exposedSkinFraction	number	optional	Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit
age	number	optional	Age in years (synthesis declines with age); omit for adult baseline
targetIU	number	optional	Vitamin D target per session in IU; default 1000
elevationM	number	optional	Ground elevation in metres (UV rises ~8%/km); default sea level

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees"
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC"
    },
    "skinType": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "description": "Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3"
    },
    "exposedSkinFraction": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "description": "Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 120,
      "description": "Age in years (synthesis declines with age); omit for adult baseline"
    },
    "targetIU": {
      "type": "number",
      "minimum": 100,
      "maximum": 10000,
      "description": "Vitamin D target per session in IU; default 1000"
    },
    "elevationM": {
      "type": "number",
      "minimum": -100,
      "maximum": 6000,
      "description": "Ground elevation in metres (UV rises ~8%/km); default sea level"
    }
  },
  "required": [
    "lat",
    "lon"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

estimate_sun_session

Estimate a sun session's outcome: 'I was (or will be) out N minutes — how much vitamin D did I make?' plus 'how long before I'd burn?' for the profile. Takes a start time (defaults to the day's best hour) and session minutes; returns estimated IU (with the physiological cap), average UV and clear-sky minutes-to-sunburn. Use for any 'how much did I get / can I get in X minutes' or 'how long without burning' question.

Parameters10

lat	number	required	Latitude in decimal degrees
lon	number	required	Longitude in decimal degrees
date	string	optional	Date as YYYY-MM-DD; defaults to today
timezone	string	optional	IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC
skinType	integer	optional	Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3
exposedSkinFraction	number	optional	Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit
age	number	optional	Age in years (synthesis declines with age); omit for adult baseline
elevationM	number	optional	Ground elevation in metres (UV rises ~8%/km); default sea level
startTime	string	optional	Local HH:MM the session starts; defaults to the day's best hour
minutes	number	required	Session length in minutes

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date as YYYY-MM-DD; defaults to today"
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC"
    },
    "skinType": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "description": "Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3"
    },
    "exposedSkinFraction": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "description": "Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 120,
      "description": "Age in years (synthesis declines with age); omit for adult baseline"
    },
    "elevationM": {
      "type": "number",
      "minimum": -100,
      "maximum": 6000,
      "description": "Ground elevation in metres (UV rises ~8%/km); default sea level"
    },
    "startTime": {
      "type": "string",
      "pattern": "^\\d{1,2}:\\d{2}$",
      "description": "Local HH:MM the session starts; defaults to the day's best hour"
    },
    "minutes": {
      "type": "number",
      "minimum": 1,
      "maximum": 600,
      "description": "Session length in minutes"
    }
  },
  "required": [
    "lat",
    "lon",
    "minutes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_my_profile

The signed-in user's saved Vitamin D profile: skin type, exposed-skin default, age, target IU and their current city. Requires connecting with OAuth (scope profile:read). Call this FIRST for any personal question, then pass its values to the public tools instead of asking the user.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_my_cities

The signed-in user's current city and favorite cities with coordinates and timezones, ready to feed into the public tools. Requires OAuth (scope profile:read).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_my_history

The signed-in user's sun history from the app's calendar: which recent days had viable sun, which they confirmed going outside, and their current streak. Requires OAuth (scope history:read).

Parameters1

days

integer

optional

How many recent days to return; default 30

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "How many recent days to return; default 30"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

log_sun_session

Marks a day as sun-confirmed in the signed-in user's history calendar — use when the user says they went (or will have gone) outside for their sun. Defaults to today. Requires OAuth (scope history:write).

Parameters2

date	string	optional	Day to confirm, YYYY-MM-DD; defaults to today
minutes	number	optional	Minutes the user reports having spent in the sun (acknowledged, not stored)

Raw schema

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Day to confirm, YYYY-MM-DD; defaults to today"
    },
    "minutes": {
      "type": "number",
      "minimum": 1,
      "maximum": 600,
      "description": "Minutes the user reports having spent in the sun (acknowledged, not stored)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

io.github.JaviMaligno/vitamind