Cerridwen¶
Cerridwen provides solar system data that is suitable for both astronomical and astrological purposes. It comes with a simple command-line utility and a JSON server, but is also designed to serve as a basis for your own application.
The motivation for this package is to have a reliable open-source library and API that provides comprehensive data on various planetary bodies and factors at a certain point in time.
Demo server¶
Take a good look first! :-)
You can check out a demo of the JSON API at this address:
This should work with your browser as well.
The current implementation of this API endpoint caches data for 10 seconds. In any case please let me know if you intend to use this for more than testing.
Starting with version 1.1.0 there’s also another endpoint with sun data:
Quickstart¶
Are you hooked by now? ;-)
Installation via pip is very simple. Here are some command lines to get you started:
pip install cerridwen
This will install Cerridwen and its dependencies. Flask will be installed when you start cerridwen-server for the first time.
To test Cerridwen’s data on the console, invoke:
cerridwen
If everything is to your satisfaction you can then start the API server if you wish:
cerridwen-server
It will start up in the foreground and listen on port 2828, serving moon data via HTTP in JSON format at the URI /v1/moon.
You can test it as follows:
curl http://localhost:2828/v1/moon
This should give you a proper JSON response with the current moon data.
Change the listen port by passing the -p switch to cerridwen-server, followed by the desired port.
FAQ¶
What zodiac is used for the longitudes?¶
All longitudes whether absolute or relative are based on the tropical zodiac. In this system of reference zero degrees refers to zero degrees tropical Aries, which in turn corresponds to the sun’s position at the vernal equinox of the year in question.
What about other planetary bodies?¶
Cerridwen’s source code is designed to be easily extensible to other planets and points. The goal is to add more planets in the future, probably starting with Mercury.
Will you add more moon data?¶
Yes! For example equatorial latitude and lunation numbers.
What’s the precision of the generated data?¶
Please see the documentation on Precision.
Hey, some of this stuff is slow!¶
You’re right! At the moment the new and full moons are computed anew everytime, which is hard on CPU power. This will change radically with the next version of the module which will have a separate lookup table generation stage for these and other events. This will also pave the way for certain new features like the lunation number.
How can I help?¶
First and foremost: use it! Also: tell your friends and fellow astronomers/astrologers!
You can also help write docs, contribute source code and tell me what you’d like to see in the project.
Donations are also welcome, they help me eat and pay my rent! :-) Even 1$ helps.
Contributing¶
Cerridwen’s codebase is on GitHub, at skypher/cerridwen.
Feel free to browse, fork and submit patches and bug reports.
Feature requests are also welcome!
If you need help, you can also write to me at <leslie.polzer@gmx.net>.
Requirements¶
Cerridwen depends on Python 3. You might be able to make it work with Python 2 as well. Patches welcome! Please let me know if there’s a version of Python 3 that does not run Cerridwen properly.
It also depends on these packages:
- pyswisseph, the Python interface to the Swiss Ephemeris library
- numpy, which Cerridwen uses for its ephemeris calculations
- Flask, if you wish to run Cerridwen’s API server
These dependencies will be installed automatically as needed.
Precision¶
There are two main data sources in Cerridwen with slightly different precision characteristics.
Most data, like planetary position and rise/set times, is pulled directly from the Swiss Ephemeris library, whose authors claim a precision of 0.001 arc seconds, or less than 2.8x10-7 degrees.
Other data like new and full moon events are generated by Cerridwen’s algorithms. The results of these algorithms are guaranteed to be exact within 10-6 degrees, or 0.0036 arc seconds. This is in fact ensured by an assertion in the code.
Thus Cerridwen’s calculations are precise enough to get event times of the ascendant and of rise and set times down to the correct second.
Warning
Please note that the current implementation of the API server uses memoization for the moon data, generating a new response every 10 seconds only due to efficiency considerations. You can easily turn this off or modify this if you run your own API server, or just wait for the next version of Cerridwen that will be able to calculate new and full moons in a more efficient manner.
Changelog¶
1.2.0¶
- Use astropy for time conversions
- Vast documentation update
- Extend test suite
- Remove sun data from moon endpoint response
1.1.0¶
- Swiss Ephemeris data files are now included in the package
- Use nose instead of doctest for quick sanity tests
- Add a lot of functions (e.g. rise/set times)
- cerridwen-server: new switch –test/-t for quick testing
- Various minor amendments and changes
- New sun data computation function and API endpoint
1.0.0¶
Initial release.
Licensing¶
Cerridwen is distributed under the MIT license:
License for Cerridwen
Copyright (c) 2014 Leslie P. Polzer <leslie.polzer@gmx.net>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Module API¶
Much of this is still missing docstrings, so this is just a rough overview.
If you need help, just shoot me a quick mail to <leslie.polzer@gmx.net> with questions.
Data computation¶
These functions take an optional Julian day (defaulting to the current point in time) and optional longitudes and latitudes, the latter of which are used for rise/set calculations. You only need to pass latitude and longitude if you want the function’s result to include rise/set data. If you do so, you must pass both latitude and longitude.
The return value of these functions is an OrderedDict.
Date utilities¶
These functions provide Julian day conversions and printable output.
HTTP API¶
- GET /v1/sun¶
Get data on the Sun.
Query Parameters: - date – reference date, in Julian day decimal format (e.g. 238490.123) or an ISO8601 time string supported by astropy.time (e.g. 2014-05-20T23:37:17)
- latitude – observer’s latitude (decimal, optional)
- longitude – observer’s longitude (decimal, optional)
Status Codes: - 200 – success
- 400 – value error; one of the parameters passed couldn’t be parsed.
Notes
- The response will include rise and set times only if both latitude and longitude are specified.
- latitude must be between and including -90 and 90.
- longitude must be between and including -180 and 180.
- The format of latitude and longitude must be something parsable by Python’s float() function.
- It is an error to specify only one of latitude and longitude
Example request:
Get sun data for the current moment, including rise and set times for Berlin.
URI: http://cerridwen.viridian-project.de/api/v1/sun?latitude=52.5&longitude=13.3
{ "jd": 2456805.9347222224, "iso_date": "2014-05-28T10:26:00Z", "position": { "absolute_degrees": 67.02621001184063, "sign": "Gemini", "deg": 7.026210011840632, "min": 1.5726007104379391, "rel_tuple": [ "Gemini", 7.026210011840632, 1.5726007104379391 ] }, "dignity": null, "next_rise": { "description": "Sun rises", "jd": 2456806.6199322133, "iso_date": "2014-05-29T02:52:42Z", "delta_days": 0.6852099909447134 }, "next_set": { "description": "Sun sets", "jd": 2456806.3022005144, "iso_date": "2014-05-28T19:15:10Z", "delta_days": 0.36747829196974635 }, "last_rise": { "description": "Sun rises", "jd": 2456805.620638409, "iso_date": "2014-05-28T02:53:43Z", "delta_days": -0.3140838132239878 }, "last_set": { "description": "Sun sets", "jd": 2456805.301308829, "iso_date": "2014-05-27T19:13:53Z", "delta_days": -0.6334133935160935 } }
- GET /v1/moon¶
Like the sun endpoint, but includes a lot more data in the response that only makes sense for the moon.
Example request:
Get moon data for the current moment, including rise and set times for the Berlin area of Germany.
URI: http://cerridwen.viridian-project.de/api/v1/sun?latitude=52.5&longitude=13.3
{ "jd": 2456805.935416667, "iso_date": "2014-05-28T10:27:00Z", "position": { "absolute_degrees": 63.00766509063341, "sign": "Gemini", "deg": 3.0076650906334095, "min": 0.4599054380045686, "rel_tuple": [ "Gemini", 3.0076650906334095, 0.4599054380045686 ] }, "phase": { "trend": "waning", "shape": "crescent", "quarter": 0, "quarter_english": "new" }, "illumination": 0.022328953544355084, "distance": 0.002617405829474053, "diameter": 30.52102695101311, "diameter_ratio": 0.2543806147943976, "speed": 12.729377304450301, "speed_ratio": 0.35293040764071915, "age": 29.175456268712878, "period_length": 29.517968974076211, "dignity": null, "next_new_moon": { "description": "Upcoming new moon in Gemini", "jd": 2456806.2779293722, "iso_date": "2014-05-28T18:40:13Z", "delta_days": 0.34251270536333323 }, "next_full_moon": { "description": "Upcoming full moon in Sagittarius", "jd": 2456821.6746404273, "iso_date": "2014-06-13T04:11:28Z", "delta_days": 15.739223760552704 }, "next_new_or_full_moon": { "description": "Upcoming new moon in Gemini", "jd": 2456806.2779293722, "iso_date": "2014-05-28T18:40:13Z", "delta_days": 0.34251270536333323 }, "last_new_moon": { "description": "Preceding new moon in Taurus", "jd": 2456776.7599603981, "iso_date": "2014-04-29T06:14:20Z", "delta_days": -29.175456268712878 }, "last_full_moon": { "description": "Preceding full moon in Scorpio", "jd": 2456792.3027133634, "iso_date": "2014-05-14T19:15:54Z", "delta_days": -13.632703303359449 }, "next_rise": { "description": "Moon rises", "jd": 2456806.653334031, "iso_date": "2014-05-29T03:40:48Z", "delta_days": 0.7179173640906811 }, "next_set": { "description": "Moon sets", "jd": 2456806.2835339396, "iso_date": "2014-05-28T18:48:17Z", "delta_days": 0.34811727283522487 }, "last_rise": { "description": "Moon rises", "jd": 2456805.624089608, "iso_date": "2014-05-28T02:58:41Z", "delta_days": -0.3113270588219166 }, "last_set": { "description": "Moon sets", "jd": 2456805.2403595136, "iso_date": "2014-05-27T17:46:07Z", "delta_days": -0.6950571532361209 } }