DOC: Expand reference doc for read_json
- [ ] closes #xxxx
- [ ] tests added / passed
- [x] passes `git diff upstream/master | flake8 --diff`
- [x] expanded reference document for `pandas.read_json()`, especially concentrating on the `orient` parameter.  Also added some example usage code and explicitly mention `to_json()` as a source of valid JSON strings.

<div class="section" id="pandas-read-json">
<h1>pandas.read_json<a class="headerlink" href="#pandas-read-json" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="pandas.read_json">
<code class="descclassname">pandas.</code><code class="descname">read_json</code><span class="sig-paren">(</span><em>path_or_buf=None</em>, <em>orient=None</em>, <em>typ='frame'</em>, <em>dtype=True</em>, <em>convert_axes=True</em>, <em>convert_dates=True</em>, <em>keep_default_dates=True</em>, <em>numpy=False</em>, <em>precise_float=False</em>, <em>date_unit=None</em>, <em>encoding=None</em>, <em>lines=False</em><span class="sig-paren">)</span><a class="reference external" href="http://github.com/pydata/pandas/blob/master/pandas/io/json.py#L112-L272"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#pandas.read_json" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a JSON string to pandas object</p>
<table class="docutils field-list" frame="void" rules="none">
<colgroup><col class="field-name">
<col class="field-body">
</colgroup><tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>path_or_buf</strong> : a valid JSON string or file-like, default: None</p>
<blockquote>
<div><p>The string could be a URL. Valid URL schemes include http, ftp, s3, and
file. For file URLs, a host is expected. For instance, a local file
could be <code class="docutils literal"><span class="pre">file://localhost/path/to/table.json</span></code></p>
</div></blockquote>
<p><strong>orient</strong> : string, indicating the expected format of the JSON input.</p>
<blockquote>
<div><p>The set of allowed orients changes depending on the value
of the <code class="docutils literal"><span class="pre">typ</span></code> parameter.</p>
<ul class="simple">
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'series'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'index'</span></code></li>
<li>The Series index must be unique for orient <code class="docutils literal"><span class="pre">'index'</span></code>.</li>
</ul>
</li>
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'frame'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index',</span>
<span class="pre">'columns','values'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'columns'</span></code></li>
<li>The DataFrame index must be unique for orients ‘index’ and
‘columns’.</li>
<li>The DataFrame columns must be unique for orients ‘index’,
‘columns’, and ‘records’.</li>
</ul>
</li>
</ul>
<p>The value of <code class="docutils literal"><span class="pre">orient</span></code> specifies the expected format of the
JSON string. The expected JSON formats are compatible with the
strings produced by <code class="docutils literal"><span class="pre">to_json()</span></code> with a corresponding value
of <code class="docutils literal"><span class="pre">orient</span></code>.</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">'split'</span></code> : dict like
<code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">[index],</span> <span class="pre">columns</span> <span class="pre">-&gt;</span> <span class="pre">[columns],</span> <span class="pre">data</span> <span class="pre">-&gt;</span> <span class="pre">[values]}</span></code></li>
<li><code class="docutils literal"><span class="pre">'records'</span></code> : list like
<code class="docutils literal"><span class="pre">[{column</span> <span class="pre">-&gt;</span> <span class="pre">value},</span> <span class="pre">...</span> <span class="pre">,</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}]</span></code></li>
<li><code class="docutils literal"><span class="pre">'index'</span></code> : dict like <code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'columns'</span></code> : dict like <code class="docutils literal"><span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'values'</span></code> : just the values array</li>
</ul>
</div></blockquote>
</div></blockquote>
<p><strong>typ</strong> : type of object to recover (series or frame), default ‘frame’</p>
<p><strong>dtype</strong> : boolean or dict, default True</p>
<blockquote>
<div><p>If True, infer dtypes, if a dict of column to dtype, then use those,
if False, then don’t infer dtypes at all, applies only to the data.</p>
</div></blockquote>
<p><strong>convert_axes</strong> : boolean, default True</p>
<blockquote>
<div><p>Try to convert the axes to the proper dtypes.</p>
</div></blockquote>
<p><strong>convert_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>List of columns to parse for dates; If True, then try to parse
datelike columns default is True; a column label is datelike if</p>
<ul class="simple">
<li>it ends with <code class="docutils literal"><span class="pre">'_at'</span></code>,</li>
<li>it ends with <code class="docutils literal"><span class="pre">'_time'</span></code>,</li>
<li>it begins with <code class="docutils literal"><span class="pre">'timestamp'</span></code>,</li>
<li>it is <code class="docutils literal"><span class="pre">'modified'</span></code>, or</li>
<li>it is <code class="docutils literal"><span class="pre">'date'</span></code></li>
</ul>
</div></blockquote>
<p><strong>keep_default_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>If parsing dates, then parse the default datelike columns</p>
</div></blockquote>
<p><strong>numpy</strong> : boolean, default False</p>
<blockquote>
<div><p>Direct decoding to numpy arrays. Supports numeric data only, but
non-numeric column and index labels are supported. Note also that the
JSON ordering MUST be the same for each term if numpy=True.</p>
</div></blockquote>
<p><strong>precise_float</strong> : boolean, default False</p>
<blockquote>
<div><p>Set to enable usage of higher precision (strtod) function when
decoding string to double values. Default (False) is to use fast but
less precise builtin functionality</p>
</div></blockquote>
<p><strong>date_unit</strong> : string, default None</p>
<blockquote>
<div><p>The timestamp unit to detect if converting dates. The default behaviour
is to try and detect the correct precision, but if this is not desired
then pass one of ‘s’, ‘ms’, ‘us’ or ‘ns’ to force parsing only seconds,
milliseconds, microseconds or nanoseconds respectively.</p>
</div></blockquote>
<p><strong>lines</strong> : boolean, default False</p>
<blockquote>
<div><p>Read the file as a json object per line.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>

</div></blockquote>

<p><strong>encoding</strong> : str, default is ‘utf-8’</p>

<blockquote>
<div><p>The encoding to use to decode py3 bytes.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>
</div></blockquote>

</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><strong>result</strong> : Series or DataFrame, depending on the value of <code class="docutils literal"><span class="pre">typ</span></code>.</p>
</td>
</tr>
</tbody>
</table>

<p class="rubric">Examples</p>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">([[</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">],</span> <span class="p">[</span><span class="s1">'c'</span><span class="p">,</span> <span class="s1">'d'</span><span class="p">]],</span>
<span class="go">                          index=['row 1', 'row 2'],</span>
<span class="go">                          columns=['col 1', 'col 2'])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span> <span class="n">df</span>
<span class="go">      col 1 col 2</span>
<span class="go">row 1     a     b</span>
<span class="go">row 2     c     d</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">orient</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">'split'</span><span class="p">,</span> <span class="s1">'records'</span><span class="p">,</span> <span class="s1">'index'</span><span class="p">]:</span>
<span class="go">        str = df.to_json(orient=orient)</span>
<span class="go">        print "'{}': '{}'".format(orient, str)</span>
<span class="go">        pd.read_json(str, orient=orient)</span>
<span class="go">'split':</span>
<span class="go">'{"columns":["col 1","col 2"],"index":["row 1","row 2"],"data":[["a","b"],</span>
<span class="go">["c","d"]]}'</span>
<span class="go">'records':</span>
<span class="go">'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'</span>
<span class="go">'index':</span>
<span class="go">'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'</span>
</pre></div>
</div>

</dd></dl>

</div>
