Merge pull request quandl#9 from ihodes/add_search

Add search functionality

Quandl/Quandl.py

@@ -2,13 +2,14 @@
 """
 Quandl's API for Python.
 
-Currently supports getting and pushing datasets.
+Currently supports getting, searching, and pushing datasets.
 
 """
 from __future__ import (print_function, division, absolute_import,
                         unicode_literals)
 import pickle
 import datetime
+import json
 import pandas as pd
 
 from dateutil import parser
@@ -23,6 +24,7 @@
     from urllib2 import HTTPError, Request, urlopen
 
 
+
 QUANDL_API_URL = 'http://www.quandl.com/api/v1/'
 
 
@@ -148,9 +150,24 @@ def push(data, code, name, authtoken='', desc='', override=False):
     return rtn
 
 
-# Helper function to parse dates with None fallback
+def search(query):
+    """Return array of dictionaries of search results.
+
+    :param str query: (required), query to search with
+    :returns: :array: search results
+
+    """
+    search_url = 'http://www.quandl.com/search/{}.json'.format(query)
+    text = urlopen(search_url).read()
+    data = json.loads(text)
+    response = data['response']
+    datasets = response['datasets']
+    return datasets
+
+
+# returns None is date is None
 def _parse_dates(date):
-    if date is None: 
+    if date is None:
         return date
     if isinstance(date, datetime.datetime):
         return date.date().isoformat()
@@ -163,15 +180,12 @@ def _parse_dates(date):
     return date.date().isoformat()
 
 
-# Helper function for actually making API call and downloading the file
 def _download(url):
     dframe = pd.read_csv(url, index_col=0, parse_dates=True)
     return dframe
 
 
-# Helper function to make html push
 def _htmlpush(url, raw_params):
-    import json
     page = url
     params = urlencode(raw_params)
     request = Request(page, params)

Quandl/__init__.py

@@ -3,4 +3,4 @@
 __all__ = ['Quandl']
 
 
-from .Quandl import get, push
+from .Quandl import get, push, search

README.md

@@ -1,34 +1,9 @@
 Quandl API for Python
-=========
+=====================
 Basic wrapper to return datasets from the Quandl website as Pandas dataframe objects with a timeseries index, or as a numpy array. This allows interactive manipulation of the results via IPython or storage of the datasets using Pandas I/O functions. You will need a familarity with [pandas](http://pandas.pydata.org/) to get the most out of this.
 
 See the [Quandl API](http://www.quandl.com/api) for more information.
 
-Example
-========
-An example of creating a pandas time series for IBM stock data, with a weekly frequency
-
-
-```python
-import Quandl
-data = Quandl.get('GOOG/NYSE_IBM', collapse='weekly')
-data.head()
-```
-
-will output
-
-```
-No authentication tokens found,usage will be limited
-Returning Dataframe for  GOOG/NYSE_IBM
-
-              Open    High     Low   Close   Volume
-Date
-2013-03-28  209.83  213.44  209.74  213.30  3752999
-2013-03-15  215.38  215.90  213.41  214.92  7937244
-2013-03-08  209.85  210.74  209.43  210.38  3700986
-2013-03-01  200.65  202.94  199.36  202.91  3309434
-2013-02-22  199.23  201.09  198.84  201.09  3107976
-```
 
 Usage
 =====
@@ -37,7 +12,6 @@ Usage is simple and mirrors the functionality found at [Quandl/API](http://www.q
 A request with a full list of options would be the following.
 
 ```python
-import Quandl
 data = Quandl.get('PRAGUESE/PX', authtoken='xxxxxx', trim_start='2001-01-01',
                   trim_end='2010-01-01', collapse='annual',
                   transformation='rdiff', rows=4, returns='numpy')
@@ -53,31 +27,62 @@ See the [pandas documentation](http://pandas.pydata.org/) for a wealth of option
 Authtokens are saved as pickled files in the local directory so it is unnecessary to enter them more than once,
 unless you change your working directory. To replace simply save the new token or delete the `authtoken.p` file.
 
-Complex Example
-===============
-Quarterly normalized crude oil prices since 2005, only returning first 4 values.
+
+## Search Example
+An example of searching for datasets having to do with oil: 
 
 ```python
 import Quandl
-data = Quandl.get('IMF/POILAPSP_INDEX', collapse='quarterly',
-                   trim_start='2005', transformation='normalize', rows='4')
+datasets = Quandl.search('OIL')
+datasets[0]
+```
+
+will output 
+
+```python
+{u'code': u'OIL',
+ u'created_at': u'2011-11-07T19:39:22Z',
+ u'description': u'Historical prices for Oil India Limited (OIL),
+                   (ISIN: INE274J01014),  National Stock Exchange of India.',
+ u'frequency': u'daily',
+ u'from_date': u'2009-09-30',
+
+ [... elided ...]
+
+ u'highlights': {u'description': u'Historical prices for <em>Oil</em> India
+                                   Limited (<em>OIL</em>), (ISIN: INE274J01014),
+                                   National Stock Exchange of India.',
+ u'name': u'<em>Oil</em> India Limited'},
+ u'import_url': u'http://www.nseindia.com/[...]'
+ u'keywords': u'Finance,India,Stocks,NSE'}
+```
+
+
+## Get Example
+An example of creating a pandas time series for IBM stock data, with a weekly frequency:
+
+```python
+data = Quandl.get('GOOG/NYSE_IBM', collapse='weekly')
 data.head()
-````
+```
 
-returns:
+will output
 
 ```
 No authentication tokens found,usage will be limited
-Returning Dataframe for  IMF/POILAPSP_INDEX
-               Price
+Returning Dataframe for  GOOG/NYSE_IBM
+
+              Open    High     Low   Close   Volume
 Date
-2013-02-28  212.792283
-2012-12-31  200.073398
-2012-09-30  210.212855
-2012-06-30  179.322638
+2013-03-28  209.83  213.44  209.74  213.30  3752999
+2013-03-15  215.38  215.90  213.41  214.92  7937244
+2013-03-08  209.85  210.74  209.43  210.38  3700986
+2013-03-01  200.65  202.94  199.36  202.91  3309434
+2013-02-22  199.23  201.09  198.84  201.09  3107976
 ```
 
-##Uploads
+
+## Push Example
 You can now upload your own data to Quandl through the Python package.
 
 At this time the only accepted format is a date indexed Pandas DataSeries.
@@ -96,26 +101,25 @@ Quandl.push(data, code='TEST', name='Test', desc='test')
 
 All parameters but desc are necessary
 
-If you wish to override the existing set at code `TEST` add `override= True`.
-
+If you wish to override the existing set at code `TEST` add `override=True`.
 
-Example
-========
-Uploading a pandas DataSeries with random data
+Uploading a pandas DataSeries with random data:
 
 ```python
 import pandas
 import numpy
-import Quandl
 
-index = ['Dec 12 2296', 'Dec 21 1998', 'Oct 9 2000', 'Oct 19 2001', 'Oct 30 2003', 'Nov 12 2003']
+index = ['Dec 12 2296', 'Dec 21 1998', 'Oct 9 2000', 'Oct 19 2001',
+         'Oct 30 2003', 'Nov 12 2003']
 data = pandas.DataFrame(numpy.random.randn(6, 3), index=index,
                         columns=['D', 'B', 'C'])
-print Quandl.push(data, code='F32C', name='Test', desc='test', authtoken='xxxxxx')
+print Quandl.push(data, code='F32C', name='Test', desc='test',
+                  authtoken='xxxxxx')
 ```
 
 Will print the link to your newly uploaded data.
 
+
 Recommended Usage
 ================
 The IPython notebook is an excellent python environment for interactive data work. Spyder is also a superb IDE for analysis and more numerical work.
@@ -125,22 +129,26 @@ in pandas itself.
 
 See [this link](http://pandas.pydata.org/pandas-docs/dev/timeseries.html) for more information about timeseries in pandas.
 
+
 Questions/Comments
 ==================
 Please send any questions, comments, or any other inquires about this package to <[email protected]>.
 
+
 Installation
 ============
 The stable version of Quandl can be installed with pip:
 
     pip install Quandl
 
+
 Dependencies
 ============
 Pandas :: <https://code.google.com/p/pandas/>
 
 dateutil (should be installed as part of pandas) :: <http://labix.org/python-dateutil>
 
+
 License
 =======
 [MIT License](http://opensource.org/licenses/MIT)