Sunrise & Sunset API

Calculate sunrise, sunset, twilight, solar noon and day length from coordinates.

GET/api/v1/sun

What It Does

Calculate sunrise, sunset, twilight, solar noon and day length from coordinates.

HTTP method: GET
Authentication: Public read-only; Bearer keys supported
Version: v1

Parameters

Name	Type	Required	Description
`city`	string	No	City lookup alternative to coordinates. Example: `Karachi`
`latitude`	number	No	Latitude, -90 to 90. Example: `24.86`
`longitude`	number	No	Longitude, -180 to 180. Example: `67.01`
`date`	date	No	Local calendar date. Defaults to today in the resolved timezone. Example: `2026-09-09`
`timezone`	string	No	IANA timezone for local output. Example: `Asia/Karachi`

Request Examples

cURL

curl -s 'https://worldclock.to/api/v1/sun?city=Karachi&latitude=24.86&longitude=67.01&date=2026-09-09&timezone=Asia/Karachi'

JavaScript

const response = await fetch("https:\/\/worldclock.to\/api\/v1\/sun?city=Karachi&latitude=24.86&longitude=67.01&date=2026-09-09&timezone=Asia\/Karachi");
const result = await response.json();
console.log(result.data);

PHP

$response = wp_remote_get('https://worldclock.to/api/v1/sun?city=Karachi&latitude=24.86&longitude=67.01&date=2026-09-09&timezone=Asia/Karachi');
 = json_decode(wp_remote_retrieve_body(), true);

Python

import requests

response = requests.get("https:\/\/worldclock.to\/api\/v1\/sun?city=Karachi&latitude=24.86&longitude=67.01&date=2026-09-09&timezone=Asia\/Karachi")
response.raise_for_status()
print(response.json()["data"])

Example Response

The values below illustrate the response shape. Live current-time fields are generated dynamically by the endpoint.

JSON

{
    "success": true,
    "data": {
        "date": "2026-09-09",
        "timezone": "Asia/Karachi",
        "latitude": 24.8599999999999994315658113919198513031005859375,
        "longitude": 67.0100000000000051159076974727213382720947265625,
        "sunrise": "2026-09-09T06:16:04+05:00",
        "sunset": "2026-09-09T18:43:31+05:00",
        "solar_noon": "2026-09-09T12:29:47+05:00",
        "civil_dawn": "2026-09-09T05:53:27+05:00",
        "civil_dusk": "2026-09-09T19:06:08+05:00",
        "day_length_seconds": 44847,
        "polar_day": false,
        "polar_night": false
    },
    "meta": {
        "version": "v1",
        "timezone": "Asia/Karachi",
        "timestamp": 1788946200
    }
}

Response Properties

Every successful response contains success: true, endpoint-specific data, and a meta object. The table below documents the public fields for this endpoint.

Property	Meaning
`success`	Boolean indicating whether the request completed successfully.
`meta.version`	Published API response version.
`meta.timestamp`	Unix timestamp for the API response instant.
`meta.timezone`	Timezone context used by the response.
`meta.rate_limit`	Per-client fair-use limit and remaining-request information on public transports.
`data.date`	Local calendar date used for calculations.
`data.timezone`	Timezone used to format returned events.
`data.latitude`	Calculation latitude.
`data.longitude`	Calculation longitude.
`data.sunrise`	Sunrise as a timezone-aware ISO 8601 datetime, or null in polar conditions.
`data.sunset`	Sunset as a timezone-aware ISO 8601 datetime, or null.
`data.solar_noon`	Approximate local solar noon.
`data.civil_dawn`	Start of civil twilight.
`data.civil_dusk`	End of civil twilight.
`data.nautical_dawn`	Start of nautical twilight when calculable.
`data.nautical_dusk`	End of nautical twilight when calculable.
`data.astronomical_dawn`	Start of astronomical twilight when calculable.
`data.astronomical_dusk`	End of astronomical twilight when calculable.
`data.day_length_seconds`	Sunrise-to-sunset duration in seconds when calculable.
`data.polar_day`	True when the sun does not set on the requested date at high latitude.
`data.polar_night`	True when the sun does not rise on the requested date at high latitude.
`data.city`	Resolved city when city lookup is used.
`data.country`	Resolved country when city lookup is used.

Errors use success: false with a stable machine-readable error code and a safe human-readable message.

Errors & HTTP Status Codes

400 — invalid or missing parameter.
401 — API key required or invalid when key-only access is enabled.
404 — unknown city, country or endpoint.
429 — configured rate limit reached.
503 — API disabled or maintenance mode.

Rate Limits & Caching

Current fair-use configuration is 60 requests per minute and 5000 requests per day. Cache stable directory/calculation responses where appropriate; treat current-time output as point-in-time data.