Skip to content

JavaScript / TypeScript SDK

Install

npm install timenow-sdk
# or
yarn add timenow-sdk

Quick Start

import { TimeNowClient } from 'timenow-sdk';

const client = new TimeNowClient('http://localhost:8090');

// Solar time for London
const result = await client.getSolarTime({ lat: 51.5074, lng: -0.1278 });
console.log(result.solarTime);            // "2026-04-14T11:49:23"
console.log(result.civilSolarOffsetMin);  // -10.6

// Social jetlag
const jetlag = await client.getJetlag({ lat: 39.47, lng: 75.99 });
console.log(jetlag.riskLevel);  // "severe"

import { TimeNowClient } from 'timenow-sdk';

const client = new TimeNowClient('http://localhost:8090');
const result = await client.getSolarTime({ lat: 51.5074, lng: -0.1278 });
console.log(result.solarTime);

const { TimeNowClient } = require('timenow-sdk');

const client = new TimeNowClient('http://localhost:8090');
client.getSolarTime({ lat: 51.5074, lng: -0.1278 }).then(console.log);

Methods

Method Parameters Returns API endpoint
getSolarTime(params) {lat, lng, utc?} Promise<SolarTimeResult> GET /solar
getJetlag(params) {lat, lng} Promise<JetlagResult> GET /solar/jetlag
getPrayerTimes(params) {lat, lng, date?, convention?} Promise<PrayerTimesResult> GET /solar/prayer
getAlmanac(params) {lat, lng, year?} Promise<AlmanacResult> GET /solar/almanac
getIcal(params) {lat, lng, days?} Promise<string> GET /solar/ical
getDeviationMap(params?) {format?} Promise<object\|string> GET /world/deviation-map
health() — Promise<boolean> GET /health

TypeScript Types

interface SolarTimeResult {
  latitude: number;
  longitude: number;
  utc: string;
  solarTime: string;
  civilTime: string;
  equationOfTimeMin: number;
  civilSolarOffsetMin: number;
  timezone: string;
  solarNoonUtc: string;
  sunriseUtc: string;
  sunsetUtc: string;
}

Error Handling

import { TimeNowClient, TimeNowError } from 'timenow-sdk';

const client = new TimeNowClient('http://localhost:8090');

try {
  await client.getSolarTime({ lat: 999, lng: 0 });
} catch (e) {
  if (e instanceof TimeNowError) {
    console.error(e.statusCode, e.message);
  }
}