Python API to AqAdvisor.com
Approximately 10% of American households have fish as pets.
It is estimated that 95% of fish deaths can be attributed to improper housing
or nutrition. Many times fish are sold or given away without any guidance to
the new pet owner, such as goldfish giveaways at carnivals or at birthdays.
Some fish have myths associated with them, such as the betta fish (siamese
fighting fish) that supposedly can live in dirty water in small bowls.
AqAdvisor.com is a website that helps aquarists plan how to stock their fish tank. Users specify their tank size, their filtration, and what fish they intend to keep in the tank. The site will calculate the stocking level and filtration capacity given the inputs. This is a useful tool to get a rough estimate on a fish tank's stocking level, it even lets you know whether the fish are compatible with one another, if you have more than one species in the tank. AqAdvisor is sometimes criticized for "not being accurate", so the output generated should be not be treated as gospel; nonetheless, it gives a reasonable starting point, and is generally very useful for beginner fishkeepers.
I started using AqAdvisor and got annoyed at the archaic design. It's not a RESTful API, it's a clunky web site that takes a while to load. I was doing lots of research and found myself wanting a better useful experience. I also had some free time on my hands one long holiday weekend so I decided to give myself a little programming exercise of creating a python API to the site.
The easiest way to use the tool is to use the ipython notebook as a starting point. First, create a stocking, then a tank, and then make a call to the AqAdvisor service. Because of the clunky web interface, multiple calls to AqAdvisor.com must be made if you want to have more than one fish species in a tank (as is would be the case for a community tank). The auto-generated AqAdvisor URL will be printed for each call out to the website. This is useful in case you want to jump over to the web UI, you can just copy and paste the URL into your web browser and continue from there.
Use the common (English) name for the fish you are looking for. PyAqAdvisor will do a "fuzzy match" to AqAdvisor's species list and match the closet one. This way you can specify your stocking list as "cardinal tetra" and not worry about the scientic name.
Please look at examples/example.py and examples/example.ipynb for more information.
Here's an example of how easy it use the new API:
from pyaqadvisor import Tank, Stocking
if __name__ == '__main__':
stocking = Stocking().add('cardinal tetra', 5)\
.add('panda cory', 6)\
.add('lemon_tetra', 12)\
.add('pearl gourami', 4)
print "My user-specified stocking is: ", stocking
print "I translate this into: ", stocking.aqadvisor_stock_list
t = Tank('55g').add_filter("AquaClear 30").add_stocking(stocking)
print "Aqadvisor tells me: ",
print t.get_stocking_level()
If you are looking for an extensive list of fish species, checkout
aqadvisor_assets.py.
PyAqAdvisor currently only works for freshwater fish species. If you are interested in saltwater fish, please contact me.
This tool was handcrafted using a combination of vi and ipython.