updated readme, added examples and returned object description concerning the API calls