{"id":15025282,"url":"https://github.com/vijinho/sun","last_synced_at":"2026-02-09T17:02:37.055Z","repository":{"id":71221181,"uuid":"153177125","full_name":"vijinho/sun","owner":"vijinho","description":"A command-line php/www rest tool for calculating sun position, sunlight phases (times for sunrise, sunset, dusk, etc.)","archived":false,"fork":false,"pushed_at":"2020-08-19T14:18:37.000Z","size":2470,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-27T07:30:54.204Z","etag":null,"topics":["api-client","api-server","geolocation","json-api","php-7","php-api","php-api-clients","php-api-server","solar","solar-system","sunrise","sunset"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vijinho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-10-15T20:27:05.000Z","updated_at":"2022-05-14T18:14:49.000Z","dependencies_parsed_at":"2023-02-22T13:30:28.300Z","dependency_job_id":null,"html_url":"https://github.com/vijinho/sun","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vijinho/sun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijinho%2Fsun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijinho%2Fsun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijinho%2Fsun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijinho%2Fsun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vijinho","download_url":"https://codeload.github.com/vijinho/sun/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijinho%2Fsun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29273139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api-client","api-server","geolocation","json-api","php-7","php-api","php-api-clients","php-api-server","solar","solar-system","sunrise","sunset"],"created_at":"2024-09-24T20:01:58.002Z","updated_at":"2026-02-09T17:02:37.032Z","avatar_url":"https://github.com/vijinho.png","language":"PHP","readme":"# sun - A command-line php/www rest tool for calculating sun position, sunlight phases (times for sunrise, sunset, dusk, etc.)\n\nCLI script `sun.php` instantiates class [gregseth/suncalc-php](https://github.com/gregseth/suncalc-php) and echoes JSON if successful\n\nThe script can also be run as a web-service with PHP's in-built webserver for testing the JSON request/responses.\n\n## Features\n\n- Runs on the command-line\n- Can be called as a stand-alone webservice using the php command line built-in server\n- Can specify a geo-location with latitude, longitude co-ordinates OR a city-id from GeoNames\n- Provided with global city data (populations \u003e 15000) from http://download.geonames.org/export/dump/ (cities15000.zip) listed/saved as JSON using --cities option, see also [data/cities15000.txt](data/cities15000.txt)\n- When calling with a city-id, adds the city information to the 'meta' information returned in the JSON result\n- Option to search for city information with --search-city\n- All messages when running with `--debug` or `--verbose` are to *stderr* to avoid interference with *stdout*\n- Specify date-format using [php date()](https://secure.php.net/manual/en/function.date.php)\n- Can output the result if successful to *stdout*\n- Errors are output in JSON as 'errors' with just a bunch of strings\n\n```\n{\n    \"errors\": [\n        \"Unable to parse --date: next sunsaday\"\n    ]\n}\n```\n\n## Returned results fields/columns/keys\n\n- timestamp - timestamp specified in for data\n- datestamp - human-readable date/time for timestamp\n- sunrise_start - sunrise starts (top edge of the sun appears on the horizon)\n- sunrise_end - sunrise ends (bottom edge of the sun appears on the horizon)\n- dawn_nautical - nautical dawn (morning nautical twilight starts)\n- dawn -  dawn (morning nautical twilight ends, morning civil twilight starts)\n- golden_hour_morning -  morning golden hour (soft light, best time for photography) ends\n- noon -  solar noon (sun is in the highest position)\n- golden_hour_evening - evening golden hour starts\n- dusk - dusk (evening nautical twilight starts)\n- dusk_nautical - nautical dusk (evening astronomical twilight starts)\n- sunset_start - sunset starts (bottom edge of the sun touches the horizon)\n- sunset_end - sunset (sun disappears below the horizon, evening civil twilight starts)\n- night - night starts (dark enough for astronomical observations)\n- nadir - nadir (darkest moment of the night, sun is in the lowest position)\n- night_end - night ends (morning astronomical twilight starts)\n\n## Instructions\n\n### Command-line options\n\n```\nUsage: php sun.php\nGet the sun phase data using class https://github.com/gregseth/suncalc-php\n(Specifying any other unknown argument options will be ignored.)\n\n        -h,  --help                   Display this help and exit\n        -v,  --verbose                Run in verbose mode\n        -d,  --debug                  Run in debug mode (implies also -v, --verbose)\n        -t,  --test                   Run in test mode, using co-ordinates for Skagen, Denmark from stormyglass.ini file by default.\n        -e,  --echo                   (Optional) Echo/output the result to stdout if successful\n        -r,  --refresh                (Optional) Force cache-refresh\n             --search-city=\u003ctext\u003e     Search for city using supplied text.\n             --city-id={city_id}      (Optional) Specify GeoNames city id (in cities.json file) for required latitude/longitude values\n             --latitude={-90 - 90}    (Required) Latitude (decimal degrees)\n             --longitude={-180 - 180} (Required) Longitude (decimal degrees)\n        -t   --date={now}             (Optional) Date/time default 'now' see: https://secure.php.net/manual/en/function.strtotime.php\n             --dir=                   (Optional) Directory for storing files (sys_get_temp_dir() if not specified)\n        -f,  --filename={output.}     (Optional) Filename for output data from operation\n             --format={json}          (Optional) Output format for output filename (reserved for future): json (default)\n             --date-format={U}        (Optional) Format to output, using date(), default unixtime, see: https://secure.php.net/manual/en/function.date.php             \n```\n\n### Requirements/Installation\n\n- PHP7\n- Create the 'cities.json' data file: `php sun.php --cities`\n\n## City-search Example\n\nSearch for 'london' and show result in 'less' command-line text viewer with debugging enabled:\n\n`php sun.php --search-city=london --echo --debug 2\u003e\u00261 | less`\n\n(Abbreviated result!)\n\n```\n[D 1/1] OPTIONS:\nArray\n(\n    [cities] =\u003e 0\n    [debug] =\u003e 1\n    [echo] =\u003e 1\n    [refresh] =\u003e 0\n    [search-city] =\u003e 1\n    [test] =\u003e 0\n    [verbose] =\u003e 1\n)\n[V 1/1] OUTPUT_FORMAT: json\n{\n    \"2643743\": {\n        \"id\": 2643743,\n        \"country_code\": \"GB\",\n        \"state\": \"ENG\",\n        \"city\": \"London\",\n        \"ascii\": \"London\",\n        \"names\": [\n            \"Gorad Londan\",\n            \"ILondon\",\n            \"LON\",\n            \"Lakana\",\n            \"Landan\",\n        ],\n        \"latitude\": 51.50853,\n        \"longitude\": -0.12574,\n        \"elevation\": 25,\n        \"population\": null,\n        \"timezone\": \"Europe\\/London\"\n    },\n}[D 2/50] Memory used (2/50) MB (current/peak).\n```\n\n### Fetch data for London\n\nThis uses city-id instead of normally required latitude/longitude and will save results to file 'london.json' as well as output to screen 'stdout'\n\n`php sun.php --city-id=2643743 --echo --filename='london.json'`\n\n*Note:* Searching with city-id returns the city information too, otherwise providing only latitude/longitude will return sun data only.\n\n```\n{\n    \"sunrise_start\": \"1539584712\",\n    \"dawn_nautical\": \"1539580374\",\n    \"dawn\": \"1539582692\",\n    \"golden_hour_morning\": \"1539587473\",\n    \"noon\": \"1539604047\",\n    \"golden_hour_evening\": \"1539620622\",\n    \"dusk\": \"1539625403\",\n    \"dusk_nautical\": \"1539627720\",\n    \"sunset_start\": \"1539623172\",\n    \"sunset_end\": \"1539623383\",\n    \"night\": \"1539630046\",\n    \"nadir\": \"1539560847\",\n    \"night_end\": \"1539578049\",\n    \"timestamp\": 1540080000,\n    \"datestamp\": \"Sun, 21 Oct 2018 00:00:00 +0000\"\n    \"city\": {\n        \"id\": 2643743,\n        \"country_code\": \"GB\",\n        \"state\": \"ENG\",\n        \"city\": \"London\",\n        \"ascii\": \"London\",\n        \"names\": [\n            \"Gorad Londan\",\n            \"ILondon\",\n            \"LON\",\n            \"Lakana\",\n            \"Landan\",\n            \"Landen\",\n            \"Ljondan\",\n            \"Llundain\",\n            \"Lodoni\",\n            \"Londain\",\n            \"Londan\",\n            \"Londar\",\n            \"Londe\",\n            \"Londen\",\n            \"Londin\",\n            \"Londinium\",\n            \"Londino\",\n            \"Londn\",\n            \"London\",\n            \"London osh\",\n            \"Londona\",\n            \"Londonas\",\n            \"Londoni\",\n            \"Londono\",\n            \"Londons\",\n            \"Londonu\",\n            \"Londra\",\n            \"Londres\",\n        ],\n        \"latitude\": 51.50853,\n        \"longitude\": -0.12574,\n        \"elevation\": 25,\n        \"population\": null,\n        \"timezone\": \"Europe\\/London\"\n    }\n}\n```\n\n### Save to file example\n\n`php sun.php --date='next year' \u003e test.json`\n\n## Running as a webservice\n\n### Starting the service\n\n1. Start the PHP webserver with `php -S 127.0.0.1:12312`\n2. Browse the URL: http://127.0.0.1:12312/sun.php with GET/POST parameters as 'date=\u003cUNIX TIMESTAMP\u003e'.\n\nAccepted request input parameters: 'date=', 'latitude=', 'longitude=', 'city-id=', 'cities', 'refresh'\n\n### Webservice Example\n\nSearch for sun phase 'next sunday' using geolocation co-ordinates for Paris:\n\nhttp://127.0.0.1:12312/sun.php?latitude=48.85341\u0026longitude=2.3488\u0026date=next%20sunday\n\nResult:\n\n```\n{\n    \"sunrise_start\": \"1540102855\",\n    \"sunrise_end\": \"1540103057\",\n    \"dawn_nautical\": \"1540098723\",\n    \"dawn\": \"1540100925\",\n    \"golden_hour_morning\": \"1540105502\",\n    \"noon\": \"1540121784\",\n    \"golden_hour_evening\": \"1540138067\",\n    \"dusk\": \"1540142644\",\n    \"dusk_nautical\": \"1540144846\",\n    \"sunset_start\": \"1540140512\",\n    \"sunset_end\": \"1540140714\",\n    \"night\": \"1540147036\",\n    \"nadir\": \"1540078584\",\n    \"night_end\": \"1540096533\",\n    \"timestamp\": 1540080000,\n    \"datestamp\": \"Sun, 21 Oct 2018 00:00:00 +0000\"\n}\n```\n\nUsing city-id:\n\n`http://127.0.0.1:12312/sun.php?city-id=2988507\u0026date=next%20sunday`\n\n```\n{\n    \"sunrise_start\": \"1540102855\",\n    \"sunrise_end\": \"1540103057\",\n    \"dawn_nautical\": \"1540098723\",\n    \"dawn\": \"1540100925\",\n    \"golden_hour_morning\": \"1540105502\",\n    \"noon\": \"1540121784\",\n    \"golden_hour_evening\": \"1540138067\",\n    \"dusk\": \"1540142644\",\n    \"dusk_nautical\": \"1540144846\",\n    \"sunset_start\": \"1540140512\",\n    \"sunset_end\": \"1540140714\",\n    \"night\": \"1540147036\",\n    \"nadir\": \"1540078584\",\n    \"night_end\": \"1540096533\",\n    \"timestamp\": 1540080000,\n    \"datestamp\": \"Sun, 21 Oct 2018 00:00:00 +0000\",\n    \"city\": {\n        \"id\": 2988507,\n        \"country_code\": \"FR\",\n        \"state\": 11,\n        \"city\": \"Paris\",\n        \"ascii\": \"Paris\",\n        \"names\": [\n            \"Baariis\",\n            \"Bahliz\",\n            \"Gorad Paryzh\",\n            \"Lungsod ng Paris\",\n            \"Lutece\",\n            \"Lutetia\",\n            \"Lutetia Parisorum\",\n            \"Lut\\u00e8ce\",\n            \"PAR\",\n            \"Pa-ri\",\n            \"Paarys\",\n            \"Palika\",\n            \"Paname\",\n            \"Pantruche\",\n            \"Paraeis\",\n            \"Paras\",\n            \"Pari\",\n            \"Paries\",\n            \"Parigge\",\n            \"Pariggi\",\n            \"Parighji\",\n            \"Parigi\",\n            \"Pariis\",\n            \"Pariisi\",\n            \"Pariizu\",\n            \"Parii\\u017eu\",\n            \"Parij\",\n            \"Parijs\",\n            \"Paris\",\n            \"Parisi\",\n            \"Parixe\",\n            \"Pariz\",\n            \"Parize\",\n            \"Parizh\",\n            \"Parizh osh\",\n            \"Parizh'\",\n            \"Parizo\",\n            \"Parizs\",\n            \"Pari\\u017e\",\n            \"Parys\",\n            \"Paryz\",\n            \"Paryzius\",\n            \"Pary\\u017c\",\n            \"Pary\\u017eius\",\n            \"Par\\u00e4is\",\n            \"Par\\u00eds\",\n            \"Par\\u00ed\\u017e\",\n            \"Par\\u00ees\",\n            \"Par\\u0129\",\n            \"Par\\u012b\",\n            \"Par\\u012bze\",\n            \"Pa\\u0159\\u00ed\\u017e\",\n            \"P\\u00e1ras\",\n            \"P\\u00e1rizs\",\n            \"Ville-Lumiere\",\n            \"Ville-Lumi\\u00e8re\",\n            \"ba li\",\n            \"barys\",\n            \"pairisa\",\n            \"pali\",\n            \"pari\",\n            \"paris\",\n            \"parys\",\n            \"paryzh\",\n            \"perisa\",\n            \"pryz\",\n            \"pyaris\",\n            \"pyarisa\",\n            \"pyrs\",\n        ],\n        \"latitude\": 48.85341,\n        \"longitude\": 2.3488,\n        \"elevation\": 42,\n        \"population\": null,\n        \"timezone\": \"Europe\\/Paris\"\n    }\n}\n```\n\n## Updating cities list\n\n- Go to [http://download.geonames.org/export/dump/](http://download.geonames.org/export/dump/)\n- Download [cities15000.zip](http://download.geonames.org/export/dump/cities15000.zip)\n- Unzip and save to [data/cities.tsv](data/cities.tsv)\n- Run script with '-r' to refresh cache and '--cities' to re-create cities.json\n\n\n----\nvijay@yoyo.org\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvijinho%2Fsun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvijinho%2Fsun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvijinho%2Fsun/lists"}