update docs in README

README.md

@@ -35,7 +35,177 @@ python setup.py install
 
 ## Examples and Usage
 
+Although not strictly required to begin interacting with the NASA API, it is recommended to sign up 
+to receive an [API access key](https://api.nasa.gov/) that has a significantly higher usage limit available compared 
+to the demo key option. Many methods do not require an API key, but for those that do, it is typically a good option to 
+use a provided API key rather than the demo key. Using a received API key allows for 1,000 requests per hour, while the 
+demo key has 30 requests limit per hour and 50 requests per day.
 
+### Authentication
+
+Assuming an API key was received after signing up, authentication to the NASA API happens when initializing the `Nasa` 
+class.
+
+~~~ python
+nasa = Nasa(key=key)
+~~~  
+
+If using a demo key, the initialization does not require any parameters to be passed.
+
+~~~ python
+nasa = Nasa()
+~~~
+
+### Remaining Requests Available
+
+The `limit_remaining` attribute of the initialized `Nasa` class allows one to see the number of available requests 
+remaining.
+
+~~~ python
+nasa.limit_remaining
+~~~
+
+### Examples
+
+The following are some quick examples to get started.
+
+#### Astronomy Picture of the Day
+
+~~~ python
+# Return today's picture of the day
+nasa.picture_of_the_day()
+# Return a previous date's picture of the day with the high-definition URL included.
+nasa.picture_of_the_day('2019-01-01', hd=True)
+~~~
+
+#### Mars Weather
+
+~~~ python
+# Return the most recent data for the previous seven Sols (Martian Days)
+nasa.mars_weather()
+~~~
+
+#### Asteroid Feed
+
+~~~ python
+# Get asteroids approaching Earth at the beginning of 2019.
+nasa.asteroid_feed(start_date='2019-01-01')
+~~~
+
+#### Get Asteroid Data
+
+~~~ python
+# Get entire asteroid data set.
+nasa.get_asteroids()
+# Get asteroid with ID 3542519
+nasa.get_asteroids(asteroid_id=3542519)
+~~~
+
+#### Coronal Mass Ejection Event Data
+
+~~~ python
+# View data from coronal mass ejection events from the last thirty days
+nasa.coronal_mass_ejection()
+# View all CME events from the beginning of 2019.
+nasa.coronal_mass_ejection(start_date='2019-01-01', end_date=datetime.datetime.today())
+~~~
+
+#### Geomagnetic Storm Event Data
+
+~~~ python
+# Get geomagnetic storm events from the last thirty days.
+nasa.geomagnetic_storm()
+~~~
+
+#### Solar Flare Event Data 
+
+~~~ python
+# Get solar flare events from May of 2019
+nasa.solar_flare(start_date='2019-05-01', end_date='2019-05-31')
+~~~
+
+#### Solar Energetic Particle Data
+
+~~~ python
+# Get data from April 2017
+nasa.solar_energetic_particle(start_date='2017-04-01', end_date='2017-04-30')
+~~~
+
+#### Magnetopause Crossing Data
+
+~~~ python
+# Get data on magnetopause crossing events from 2018 to the current date.
+nasa.magnetopause_crossing(start_date='2018-01-01')
+~~~
+
+#### Radiation Belt Enhancement Data
+
+~~~ python
+# Get data on radiation belt enhancement events from the last 30 days.
+nasa.radiation_belt_enhancement()
+~~~ 
+
+#### Hight Speed Stream Data
+
+~~~ python
+# Get data on hight speed stream events from the beginning of September 2019.
+nasa.hight_speed_stream()
+~~~
+
+#### WSA Enlil-Simulation Data
+
+~~~ python
+# Get data from the first simulation performed in 2019.
+wsa = n.wsa_enlil_simulation(start_date='2019-01-01')
+wsa[0]
+~~~ 
+
+#### EPIC (DSCOVR's Earth Polychromatic Imaging Camera)
+
+~~~ python
+# Get EPIC data from the beginning of 2019.
+e = nasa.epic(date='2019-01-01')
+# Print the first result
+e[0]
+~~~
+
+#### Landsat Images for a given Latitude-Longitude
+
+~~~ python
+# Get imagery at latitude 1.5, longitude 100.75 and include the computed cloud score calculation.
+nasa.earth_imagery(lon=100.75, lat=1.5, cloud_score=True)
+~~~ 
+
+#### Available Image data collected by the Mars rovers Curiosity, Discovery and Spirit.
+
+~~~ python
+# Return image data collected on Curiosity's 1000th sol.
+nasa.mars_rover(sol=1000)
+~~~
+
+#### Access GeneLab and Other Bioinformatics Databases
+
+~~~ python
+
+~~~ 
+
+The following functions do not require authentication with an API or demo key.
+
+#### CelesTrak Two-Line Element Set Records
+
+~~~ python
+# Retrieve available data for a specific satellite ID.
+tle(satellite_number=43553)
+~~~ 
+
+#### Search for Available Imagery and Audio from the images.nasa.gov API
+
+~~~ python
+# Search for media related to 'apollo 11' with 'moon landing' in the description of the items.
+r = media_search(query='apollo 11', description='moon landing')
+# Print the first returned media item from the resulting collection.
+r['items'][0]
+~~~
 
 ## Requirements
 

nasapy/api.py

@@ -125,7 +125,7 @@ def mars_weather_limit_remaining(self, remaining):
 
     def picture_of_the_day(self, date=None, hd=False):
         r"""
-        Returns the URL and other information for the NASA Picture of the Day.
+        Returns the URL and other information for the NASA Astronomy Picture of the Day.
 
         Parameters
         ----------
@@ -161,8 +161,8 @@ def picture_of_the_day(self, date=None, hd=False):
         """
         if date is not None:
             if not isinstance(date, (str, datetime.datetime)):
-                raise TypeError('date parameter must be a string representing a date in YYYY-MM-DD format or a datetime '
-                                'object.')
+                raise TypeError('date parameter must be a string representing a date in YYYY-MM-DD format or a '
+                                'datetime object.')
 
         if not isinstance(hd, bool):
             raise TypeError('hd parameter must be True or False (boolean).')
@@ -1579,7 +1579,7 @@ def media_search(query=None, center=None, description=None, keywords=None, locat
                  nasa_id=None, page=1, photographer=None, secondary_creator=None, title=None, year_start=None,
                  year_end=None):
     r"""
-    Performs a general search for images from the images.nasa.gov API based on parameters and criteria specified.
+    Performs a general search for media from the images.nasa.gov API based on parameters and criteria specified.
     At least one parameter must be provided.
 
     Parameters
@@ -2711,15 +2711,6 @@ def _media_assets(endpoint, nasa_id):
 
 
 def _donki_request(key, url, start_date=None, end_date=None):
-    r"""
-
-    Parameters
-    ----------
-
-    Returns
-    -------
-
-    """
     start_date, end_date = _check_dates(start_date=start_date, end_date=end_date)
 
     r = requests.get(url,
@@ -2743,15 +2734,6 @@ def _donki_request(key, url, start_date=None, end_date=None):
 
 
 def _check_dates(start_date=None, end_date=None):
-    r"""
-
-    Parameters
-    ----------
-
-    Returns
-    -------
-
-    """
     if start_date is not None:
         if not isinstance(start_date, (str, datetime.datetime)):
             raise TypeError('start_date parameter must be a string representing a date in YYYY-MM-DD format or '