Skip to main content

A wrapper for WorldtimeAPI with search functionality.

Project description



Worldtime-py is a Python wrapper for WorldtimeAPI. It is able to search through the endpoints of the API to find the closest location if the exact one could not be found. It reduces the strain and the difficulty of getting the time for the location desired.

WorldtimeAPI is a JSON API for obtaining the current time in, and related data about, a timezone. It gives data suh as the UTC offset, whether that timezone is in Daylight Savings Time (DST), UTC offset, etc.


This library can be installed by using pip install worldtimepy. Doing so will automatically install all requirements.


This library requires you to have requests, unidecode, and countryinfo. All of those can be installed using pip.

Using the wrapper

class worldtime.WorldTime()

This is the main class through which you should interact with the API.


Has all existing locations from WorldtimeAPI.

return list

.from_ip(ip: str='') -> TimeInfo optional argument: ip

Takes an IP and returns a corresponding TimeInfo object with timezone information for that IP. If no IP is provided, it will use the requesting IP.

return TimeInfo

.find_by_name(name: str) -> list

Takes a string and returns a list of strings for all locations that contain that name.

return list

.search(name: str) -> str

Takes a country name or a city name and tries to find it in the database. It returns a string that can be used by get_location().

Warning: This function iterates through different databases to try and locate the query. It may be slow.

return string

.get_location(location: str) -> object

Takes a proper location taken from search or find_by_name and returns a TimeInfo object.

return TimeInfo


Gathers new data for self.locations.

No return

class timeinfo.TimeInfo(to_get=0, ip: bool=False)

This class takes a location found through one of the other methods and makes an object with information for that timezone. You can use any location from worldtime.WorldTime().locations here.

Alternatively, if you set ip to True, you may provide an IPv4 address on to_get to get time information for that IP. If ip is set to True and nothing is given to to_get, the machine's IP will be used.

Printing or turning this object into a string returns a prettier string containing time information.

2021-06-11 00:14:14.378300 UTC-0700

Full json pulled from the API.

return dict


Returns current day of the week.

return int


Returns current day of the year.

return int


Returns current number of the week of the year.

return int


Returns an aware datetime object.

return datetime


Returns a string version of a datetime object.

return str


Returns a string representing the abbreviated format of the timezone. E.g. 'PST'

return str


Returns whether timezone is in daylight savings time.

return bool



Returns a unix like time integer.

return int


Returns the UTC time..

return str


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

worldtimepy-0.1.1.tar.gz (17.4 kB view hashes)

Uploaded source

Built Distribution

worldtimepy-0.1.1-py3-none-any.whl (17.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page