DOC: Expand on reference docs for read_json
State: closed

- [ ] closes #xxxx
- [ ] tests added / passed
- [x] passes `git diff upstream/master | flake8 --diff`
- [] whatsnew entry

Continuation of closed PR #14284
Documentation update for `read_json()`.
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/pandas-dev/pandas/blob/master/pandas/io/json.py#L112-L286"><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,</p>
<blockquote>
<div><p>Indication of expected JSON string format.
Compatible JSON strings can be produced by <code class="docutils literal"><span class="pre">to_json()</span></code> with a
corresponding orient value.
The set of possible orients is:</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>
<p>The allowed and default values depend on the value
of the <cite>typ</cite> 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 <code class="docutils literal"><span class="pre">'index'</span></code> and
<code class="docutils literal"><span class="pre">'columns'</span></code>.</li>
<li>The DataFrame columns must be unique for orients <code class="docutils literal"><span class="pre">'index'</span></code>,
<code class="docutils literal"><span class="pre">'columns'</span></code>, and <code class="docutils literal"><span class="pre">'records'</span></code>.</li>
</ul>
</li>
</ul>
</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 <cite>typ</cite>.</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="gp">... </span>                  <span class="n">index</span><span class="o">=</span><span class="p">[</span><span class="s1">'row 1'</span><span class="p">,</span> <span class="s1">'row 2'</span><span class="p">],</span>
<span class="gp">... </span>                  <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s1">'col 1'</span><span class="p">,</span> <span class="s1">'col 2'</span><span class="p">])</span>
</pre></div>
</div>

<p>Encoding/decoding a Dataframe using <code class="docutils literal"><span class="pre">'split'</span></code> formatted JSON:</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">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'split'</span><span class="p">)</span>
<span class="go">'{"columns":["col 1","col 2"],</span>
<span class="go">  "index":["row 1","row 2"],</span>
<span class="go">  "data":[["a","b"],["c","d"]]}'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'split'</span><span class="p">)</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>
</pre></div>
</div>

<p>Encoding/decoding a Dataframe using <code class="docutils literal"><span class="pre">'index'</span></code> formatted JSON:</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">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'index'</span><span class="p">)</span>
<span class="go">'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'index'</span><span class="p">)</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>
</pre></div>
</div>

<p>Encoding/decoding a Dataframe using <code class="docutils literal"><span class="pre">'records'</span></code> formatted JSON.
Note that index labels are not preserved with this encoding.</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">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'records'</span><span class="p">)</span>
<span class="go">'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'records'</span><span class="p">)</span>
<span class="go">  col 1 col 2</span>
<span class="go">0     a     b</span>
<span class="go">1     c     d</span>
</pre></div>
</div>

</dd></dl>

</div>


Labels:
name: Docs
name: IO JSON
description: read_json, to_json, json_normalize

Comments:
## [Current coverage](https://codecov.io/gh/pandas-dev/pandas/pull/14442?src=pr) is 85.25% (diff: 100%)

> Merging [#14442](https://codecov.io/gh/pandas-dev/pandas/pull/14442?src=pr) into [master](https://codecov.io/gh/pandas-dev/pandas/branch/master?src=pr) will decrease coverage by **<.01%**

``` diff
@@             master     #14442   diff @@
==========================================
  Files           140        140          
  Lines         50631      50631          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
- Hits          43167      43166     -1   
- Misses         7464       7465     +1   
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last update [7cad3f1...bdc25b7](https://codecov.io/gh/pandas-dev/pandas/compare/7cad3f16bccd1d4702ef9d038b1ee0db33b9bb94...bdc25b730ffbd01514d4f8b62774b437e6fa3098?src=pr)

does this need corresponding updates in `read_json`?

@cswarth Thanks a lot! 
If you want to improve the `to_json` docstring with some examples as well, very welcome!