{"id":22045246,"url":"https://github.com/nigelhorne/timezone-timezonedb","last_synced_at":"2025-03-23T14:15:43.042Z","repository":{"id":151824965,"uuid":"624872455","full_name":"nigelhorne/TimeZone-TimeZoneDB","owner":"nigelhorne","description":"Interface to https://timezonedb.com/ for looking up timezones","archived":false,"fork":false,"pushed_at":"2025-02-07T20:12:41.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-07T20:33:05.778Z","etag":null,"topics":["cpan","perl","timezone"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nigelhorne.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-07T13:19:53.000Z","updated_at":"2025-02-07T20:12:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"f47c0c25-cc97-4d28-b1e6-ba2cdb8419f5","html_url":"https://github.com/nigelhorne/TimeZone-TimeZoneDB","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FTimeZone-TimeZoneDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FTimeZone-TimeZoneDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FTimeZone-TimeZoneDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FTimeZone-TimeZoneDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigelhorne","download_url":"https://codeload.github.com/nigelhorne/TimeZone-TimeZoneDB/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245111946,"owners_count":20562512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpan","perl","timezone"],"created_at":"2024-11-30T13:12:24.506Z","updated_at":"2025-03-23T14:15:43.008Z","avatar_url":"https://github.com/nigelhorne.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nTimeZone::TimeZoneDB - Interface to [https://timezonedb.com](https://timezonedb.com) for looking up Timezone data\n\n# VERSION\n\nVersion 0.03\n\n# SYNOPSIS\n\n    use TimeZone::TimeZoneDB;\n\n    my $tzdb = TimeZone::TimeZoneDB-\u003enew(key =\u003e 'XXXXXXXX');\n    my $tz = $tzdb-\u003eget_time_zone({ latitude =\u003e 0.1, longitude =\u003e 0.2 });\n\n# DESCRIPTION\n\nThe `TimeZone::TimeZoneDB` Perl module provides an interface to the [https://timezonedb.com](https://timezonedb.com) API,\nenabling users to retrieve timezone data based on geographic coordinates.\nIt supports configurable HTTP user agents, allowing for proxy settings and request throttling.\nThe module includes robust error handling, ensuring proper validation of input parameters and secure API interactions.\nJSON responses are safely parsed with error handling to prevent crashes.\nDesigned for flexibility,\nit allows users to override default configurations while maintaining a lightweight and efficient structure for querying timezone information.\n\n- Caching\n\n    Identical requests are cached (using [CHI](https://metacpan.org/pod/CHI) or a user-supplied caching object),\n    reducing the number of HTTP requests to the API and speeding up repeated queries.\n\n    This module leverages [CHI](https://metacpan.org/pod/CHI) for caching geocoding responses.\n    When a geocode request is made,\n    a cache key is constructed from the request.\n    If a cached response exists,\n    it is returned immediately,\n    avoiding unnecessary API calls.\n\n- Rate-Limiting\n\n    A minimum interval between successive API calls can be enforced to ensure that the API is not overwhelmed and to comply with any request throttling requirements.\n\n    Rate-limiting is implemented using [Time::HiRes](https://metacpan.org/pod/Time%3A%3AHiRes).\n    A minimum interval between API\n    calls can be specified via the `min_interval` parameter in the constructor.\n    Before making an API call,\n    the module checks how much time has elapsed since the\n    last request and,\n    if necessary,\n    sleeps for the remaining time.\n\n# METHODS\n\n## new\n\n    my $tzdb = TimeZone::TimeZoneDB-\u003enew();\n    my $ua = LWP::UserAgent::Throttled-\u003enew();\n    $ua-\u003eenv_proxy(1);\n    $tzdb = TimeZone::TimeZoneDB-\u003enew(ua =\u003e $ua, key =\u003e 'XXXXX');\n\n    my $tz = $tzdb-\u003etz({ latitude =\u003e 51.34, longitude =\u003e 1.42 })-\u003e{'zoneName'};\n    print \"Ramsgate's time zone is $tz.\\n\";\n\nCreates a new instance. Acceptable options include:\n\n- `ua`\n\n    An object to use for HTTP requests.\n    If not provided, a default user agent is created.\n\n- `host`\n\n    The API host endpoint.\n    Defaults to [https://api.timezonedb.com](https://api.timezonedb.com)\n\n- `cache`\n\n    A caching object.\n    If not provided,\n    an in-memory cache is created with a default expiration of one hour.\n\n- `min_interval`\n\n    Minimum number of seconds to wait between API requests.\n    Defaults to `0` (no delay).\n    Use this option to enforce rate-limiting.\n\n## get\\_time\\_zone\n\n    use Geo::Location::Point;\n\n    my $ramsgate = Geo::Location::Point-\u003enew({ latitude =\u003e 51.34, longitude =\u003e 1.42 });\n    # Find Ramsgate's time zone\n    $tz = $tzdb-\u003eget_time_zone($ramsgate)-\u003e{'zoneName'}, \"\\n\";\n\n## ua\n\nAccessor method to get and set UserAgent object used internally. You\ncan call _env\\_proxy_ for example, to get the proxy information from\nenvironment variables:\n\n    $tzdb-\u003eua()-\u003eenv_proxy(1);\n\nFree accounts are limited to one search a second,\nso you can use [LWP::UserAgent::Throttled](https://metacpan.org/pod/LWP%3A%3AUserAgent%3A%3AThrottled) to keep within that limit.\n\n    use LWP::UserAgent::Throttled;\n\n    my $ua = LWP::UserAgent::Throttled-\u003enew();\n    $ua-\u003ethrottle('timezonedb.com' =\u003e 1);\n    $tzdb-\u003eua($ua);\n\n# AUTHOR\n\nNigel Horne, `\u003cnjh@bandsman.co.uk\u003e`\n\nThis library is free software; you can redistribute it and/or modify\nit under the same terms as Perl itself.\n\nLots of thanks to the folks at [https://timezonedb.com](https://timezonedb.com).\n\n# BUGS\n\nThis module is provided as-is without any warranty.\n\nPlease report any bugs or feature requests to `bug-timezone-timezonedb at rt.cpan.org`,\nor through the web interface at\n[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=TimeZone-TimeZoneDB](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=TimeZone-TimeZoneDB).\nI will be notified, and then you'll\nautomatically be notified of progress on your bug as I make changes.\n\n# SEE ALSO\n\nTimezoneDB API: [https://timezonedb.com/api](https://timezonedb.com/api)\n\n# LICENSE AND COPYRIGHT\n\nCopyright 2023-2025 Nigel Horne.\n\nThis program is released under the following licence: GPL2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Ftimezone-timezonedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigelhorne%2Ftimezone-timezonedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Ftimezone-timezonedb/lists"}