TimeZoneDB - Ismena website

info@ismena.com

TimeZoneDB Connector

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

Overview

The TimeZoneDB Connector facilitates seamless integration with providing access to time zone data, including supported time zones, local time details, and time conversions between zones. This connector acts as a proxy to streamline data retrieval, supporting actions for listing time zones, retrieving local time data, and converting timestamps between time zones. This supports JSON and XML response formats.

Integration Overview

This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the TimeZoneDB Connector.

Supported Integration Action Points

listTimeZones: Retrieves a list of supported time zones, optionally filtered by country or zone name.
getTimeZone: Retrieves local time data by zone, position, city, or IP (IP lookup requires a premium plan).
convertTimeZone: Converts a Unix timestamp between two time zones.

Detailed Integration Documentation

2.1 List Time Zones Retrieval

Action	listTimeZones
Purpose	Retrieves a comprehensive list of supported time zones, optionally filtered by country code or zone name. Useful for building time zone selection interfaces.
Parameters	Required: key: Your API key (string, e.g., YOUR-API-KEY). Register at the TimeZoneDB website to obtain. Optional: format: Response format (string, enum: [json, xml], default: xml). country: ISO 3166 country code filter (string, e.g., US). zone: Zone name filter, supports wildcard * (string, e.g., America*). fields: Comma-separated fields to include in the response (string, e.g., countryCode,zoneName).
Configuration	Ensure the connector is configured with the base URL via the CONNECTOR_ENV_TIMEZONEDB_BASE_URL environment variable.
Output	Successful: Returns a JSON or XML object with: status: Success status (string, e.g., OK). message: Error message if applicable (string, e.g., ""). zones: Array of objects containing: countryCode: ISO 3166 country code (string, e.g., US). countryName: Country name (string, e.g., United States). zoneName: Time zone name (string, e.g., America/New_York). gmtOffset: Seconds offset from UTC (integer, e.g., -14400). dst: DST status (integer, 1 = DST in effect, 0 otherwise). timestamp: Current local time in Unix time (integer, e.g., 1585262700). Failure: Returns error details (e.g., status: ERROR, message: invalid API key).
Workflow Example	Configure the connector with the appropriate base URL. Execute the listTimeZones action with key and optional country=US. Process the response to populate a time zone selection dropdown.

2.2 Get Time Zone Retrieval

Action	getTimeZone
Purpose	Retrieves detailed local time data by time zone, geographic position, city, or IP address (IP lookup requires a premium plan). Helps obtain precise time zone information.
Parameters	Required: key: Your API key (string, e.g., YOUR-API-KEY). by: Lookup method (string, enum: [zone, position, city, ip]). Optional: format: Response format (string, enum: [json, xml]). callback: JSONP callback name (string, e.g., myCallback). fields: Comma-separated output fields (string, e.g., zoneName,formatted). zone: Time zone name or abbreviation (string, e.g., America/New_York, required if by=zone). lat: Latitude (float, e.g., 40.7128, required if by=position). lng: Longitude (float, e.g., -74.0060, required if by=position). country: ISO country code (string, e.g., US, required if by=city). region: Region code (string, e.g., NY, required if by=city, US only). city: City name (string, e.g., New York, required if by=city). ip: IP address (string, e.g., 192.168.1.1, required if by=ip).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON or XML object with: status: Success status (string, e.g., OK). message: Error message if applicable (string, e.g., ""). countryCode: ISO 3166 country code (string, e.g., US). countryName: Country name (string, e.g., United States). regionName: Region name (string, e.g., New York). cityName: City name (string, e.g., New York). zoneName: Time zone name (string, e.g., America/New_York). abbreviation: Time zone abbreviation (string, e.g., EDT). gmtOffset: Seconds offset from UTC (integer, e.g., -14400). dst: DST status (integer, 1 = DST in effect, 0 otherwise). zoneStart: Unix timestamp of zone start (integer, e.g., 1585262700). zoneEnd: Unix timestamp of zone end (integer, e.g., 0). nextAbbreviation: Next abbreviation if applicable (string, e.g., EST). timestamp: Current local time in Unix time (integer, e.g., 1585262700). formatted: Local time in human-readable form (string, e.g., 2020-03-27 00:00:00 EDT). Failure: Returns error details (e.g., status: ERROR, message: invalid time zone).
Workflow Example	Execute the getTimeZone action with key, by=zone, and zone=America/New_York. Review the response to obtain local time and DST status. Use the data for scheduling or time display applications.

2.3 Convert Time Zone Retrieval

Action	convertTimeZone
Purpose	Converts a Unix timestamp between two time zones, enabling applications to display or calculate time differences across zones.
Parameters	Required: key: Your API key (string, e.g., YOUR-API-KEY). from: Source time zone name or abbreviation (string, e.g., America/New_York). to: Destination time zone name or abbreviation (string, e.g., Europe/London). Optional: format: Response format (string, enum: [json, xml]). time: Unix timestamp in seconds (integer, e.g., 1585262700, default: current UTC time).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON or XML object with: status: Success status (string, e.g., OK). message: Error message if applicable (string, e.g., ""). fromZoneName: Source time zone name (string, e.g., America/New_York). fromAbbreviation: Source time zone abbreviation (string, e.g., EDT). fromTimestamp: Source timestamp (integer, e.g., 1585262700). toZoneName: Destination time zone name (string, e.g., Europe/London). toAbbreviation: Destination time zone abbreviation (string, e.g., BST). toTimestamp: Destination timestamp (integer, e.g., 1585277100). toFormatted: Destination time in human-readable form (string, e.g., 2020-03-27 04:00:00 BST). offset: Seconds difference between zones (integer, e.g., 14400). Failure: Returns error details (e.g., status: ERROR, message: invalid time zone).
Workflow Example	Execute the convertTimeZone action with key, from=America/New_York, to=Europe/London, and optional time=1585262700. Save the converted timestamp and formatted time for scheduling or display. Use the offset for time difference calculations.

Workflow Creation with the Connector

Example Workflow: Time Zone Selection and Conversion

Retrieve Supported Time Zones	Use the listTimeZones action with key and optional country=US to fetch a list of available time zones. Identify target time zones (e.g., America/New_York, Europe/London).
Query Local Time	Execute the getTimeZone action with key, by=zone, and zone=America/New_York to fetch local time data. Process the response to display local time in a user interface.
Perform Time Zone Conversion	Use the convertTimeZone action with key, from=America/New_York, to=Europe/London, and optional time to convert a timestamp. Integrate the converted time into a scheduling application or global time display.

This workflow enables applications to provide users with accurate time zone data and conversions, enhancing global time management and scheduling capabilities.

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to IBM x iSolution Event