Add Placekey API client (#1)

* Add API client API client working * Increment version number * Force utf-8 encoding of request payloads * Update sphinx files to include API client * Update docs * Fix custom query id handling * Update README with API examples
Placekey · Nov 6, 2020 · d524bc1 · d524bc1
1 parent 4b63d09
commit d524bc1
Show file tree

Hide file tree

Showing 19 changed files with 814 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ A Python library for working with [Placekeys](https://placekey.io). Documentatio
 ## Installation
 
 This package can be installed from [PyPI](https://pypi.org/project/placekey/) by
+
 ```shell script
 pip install placekey
 ```
@@ -49,6 +50,7 @@ The distance in meters between two Placekeys can be found with the following fun
 ```
 
 An upper bound on the maximal distance in meters between two Placekeys based on the length of their shared prefix is provided by `placekey.get_prefix_distance_dict()`.
+
 ```python
 >>> pk.get_prefix_distance_dict()
 {0: 20040000.0,
@@ -75,6 +77,68 @@ True
 False
 ```
 
+## API Client
+
+This package also includes a client for the Placekey API. The methods in the client are automatically rate limited.
+
+```python
+>>> from placekey.api import PlacekeyAPI
+>>> placekey_api_key = "..."
+>>> pk_api = PlacekeyAPI(placekey_api_key)
+```
+
+The `PlacekeyAPI.lookup_placekey` method can be used to lookup the Placekey for a single place.
+
+```python
+>>> pk_api.lookup_placekey(latitude=37.7371, longitude=-122.44283)
+{'query_id': '0', 'placekey': '@5vg-82n-kzz'}
+```
+
+```python
+>>> place = {
+>>>   "street_address": "598 Portola Dr",
+>>>   "city": "San Francisco",
+>>>   "region": "CA",
+>>>   "postal_code": "94131",
+>>>   "iso_country_code": "US"
+>>> }
+>>> pk_api.lookup_placekey(**place, strict_address_match=True)
+{'query_id': '0', 'placekey': '227@5vg-82n-pgk'}
+```
+
+The `PlacekeyAPI.lookup_placekeys` method can be used to lookup Placekeys for multiple places.
+
+```python
+>>> places = [
+>>>   {
+>>>     "street_address": "1543 Mission Street, Floor 3",
+>>>     "city": "San Francisco",
+>>>     "region": "CA",
+>>>     "postal_code": "94105",
+>>>     "iso_country_code": "US"
+>>>   },
+>>>   {
+>>>     "query_id": "thisqueryidaloneiscustom",
+>>>     "location_name": "Twin Peaks Petroleum",
+>>>     "street_address": "598 Portola Dr",
+>>>     "city": "San Francisco",
+>>>     "region": "CA",
+>>>     "postal_code": "94131",
+>>>     "iso_country_code": "US"
+>>>   },
+>>>   {
+>>>     "latitude": 37.7371,
+>>>     "longitude": -122.44283
+>>>   }
+>>> ]
+>>> pk_api.lookup_placekeys(places)
+[{'query_id': '0', 'placekey': '226@5vg-7gq-5mk'},
+ {'query_id': 'thisqueryidaloneiscustom', 'placekey': '227-222@5vg-82n-pgk'},
+ {'query_id': '2', 'placekey': '@5vg-82n-kzz'}]
+```
+
+Full details on how to query the API and how to get an API key can be found [here](https://docs.placekey.io/).
+
 ## Notebooks
 
 Jupyter notebooks demonstrating various Placekey functionality are contained in the [placekey-notebooks](https://github.com/Placekey/placekey-notebooks) repository.

diff --git a/docs/_modules/index.html b/docs/_modules/index.html
@@ -36,7 +36,8 @@ <h3>Navigation</h3>
           <div class="body" role="main">
 
   <h1>All modules for which code is available</h1>
-<ul><li><a href="placekey/placekey.html">placekey.placekey</a></li>
+<ul><li><a href="placekey/api.html">placekey.api</a></li>
+<li><a href="placekey/placekey.html">placekey.placekey</a></li>
 </ul>
 
             <div class="clearer"></div>

diff --git a/docs/_modules/placekey/api.html b/docs/_modules/placekey/api.html
diff --git a/docs/_sources/modules.rst.txt b/docs/_sources/modules.rst.txt
@@ -1,4 +1,4 @@
-placekey
+Placekey
 ========
 
 .. toctree::

diff --git a/docs/_sources/placekey.rst.txt b/docs/_sources/placekey.rst.txt
@@ -1,8 +1,15 @@
-placekey package
+Submodules
 ================
 
-placekey.placekey module
-------------------------
+placekey.api
+------------
+
+.. automodule:: placekey.api
+   :members:
+   :show-inheritance:
+
+placekey.placekey
+-----------------
 
 .. automodule:: placekey.placekey
    :members:

diff --git a/docs/genindex.html b/docs/genindex.html
@@ -41,6 +41,7 @@ <h1 id="index">Index</h1>
 <div class="genindex-jumpbox">
  <a href="#G"><strong>G</strong></a>
  | <a href="#H"><strong>H</strong></a>
+ | <a href="#L"><strong>L</strong></a>
  | <a href="#M"><strong>M</strong></a>
  | <a href="#P"><strong>P</strong></a>
  | <a href="#W"><strong>W</strong></a>
@@ -72,13 +73,29 @@ <h2 id="H">H</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="L">L</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="placekey.html#placekey.api.PlacekeyAPI.lookup_batch">lookup_batch() (placekey.api.PlacekeyAPI method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="placekey.html#placekey.api.PlacekeyAPI.lookup_placekey">lookup_placekey() (placekey.api.PlacekeyAPI method)</a>
+</li>
+      <li><a href="placekey.html#placekey.api.PlacekeyAPI.lookup_placekeys">lookup_placekeys() (placekey.api.PlacekeyAPI method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
 <h2 id="M">M</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li>
     module
 
       <ul>
+        <li><a href="placekey.html#module-placekey.api">placekey.api</a>
+</li>
         <li><a href="placekey.html#module-placekey.placekey">placekey.placekey</a>
 </li>
       </ul></li>
@@ -89,6 +106,13 @@ <h2 id="P">P</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li>
+    placekey.api
+
+      <ul>
+        <li><a href="placekey.html#module-placekey.api">module</a>
+</li>
+      </ul></li>
+      <li>
     placekey.placekey
 
       <ul>
@@ -100,11 +124,11 @@ <h2 id="P">P</h2>
       <li><a href="placekey.html#placekey.placekey.placekey_format_is_valid">placekey_format_is_valid() (in module placekey.placekey)</a>
 </li>
       <li><a href="placekey.html#placekey.placekey.placekey_to_geo">placekey_to_geo() (in module placekey.placekey)</a>
-</li>
-      <li><a href="placekey.html#placekey.placekey.placekey_to_geojson">placekey_to_geojson() (in module placekey.placekey)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="placekey.html#placekey.placekey.placekey_to_geojson">placekey_to_geojson() (in module placekey.placekey)</a>
+</li>
       <li><a href="placekey.html#placekey.placekey.placekey_to_h3">placekey_to_h3() (in module placekey.placekey)</a>
 </li>
       <li><a href="placekey.html#placekey.placekey.placekey_to_h3_int">placekey_to_h3_int() (in module placekey.placekey)</a>
@@ -114,6 +138,8 @@ <h2 id="P">P</h2>
       <li><a href="placekey.html#placekey.placekey.placekey_to_polygon">placekey_to_polygon() (in module placekey.placekey)</a>
 </li>
       <li><a href="placekey.html#placekey.placekey.placekey_to_wkt">placekey_to_wkt() (in module placekey.placekey)</a>
+</li>
+      <li><a href="placekey.html#placekey.api.PlacekeyAPI">PlacekeyAPI (class in placekey.api)</a>
 </li>
       <li><a href="placekey.html#placekey.placekey.polygon_to_placekeys">polygon_to_placekeys() (in module placekey.placekey)</a>
 </li>

diff --git a/docs/index.html b/docs/index.html
@@ -15,7 +15,7 @@
     <script src="_static/language_data.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="placekey" href="modules.html" /> 
+    <link rel="next" title="Placekey" href="modules.html" /> 
   </head><body>
     <div class="related" role="navigation" aria-label="related navigation">
       <h3>Navigation</h3>
@@ -27,7 +27,7 @@ <h3>Navigation</h3>
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="modules.html" title="placekey"
+          <a href="modules.html" title="Placekey"
              accesskey="N">next</a> |</li>
         <li class="nav-item nav-item-0"><a href="#">placekey 0.0.1 documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Placekey-py documentation</a></li> 
@@ -45,8 +45,8 @@ <h1>Placekey-py documentation<a class="headerlink" href="#placekey-py-documentat
 <div class="toctree-wrapper compound">
 <p class="caption"><span class="caption-text">Contents:</span></p>
 <ul>
-<li class="toctree-l1"><a class="reference internal" href="modules.html">placekey</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="placekey.html">placekey package</a></li>
+<li class="toctree-l1"><a class="reference internal" href="modules.html">Placekey</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="placekey.html">Submodules</a></li>
 </ul>
 </li>
 </ul>
@@ -76,7 +76,7 @@ <h3><a href="#">Table of Contents</a></h3>
 
   <h4>Next topic</h4>
   <p class="topless"><a href="modules.html"
-                        title="next chapter">placekey</a></p>
+                        title="next chapter">Placekey</a></p>
   <div role="note" aria-label="source link">
     <h3>This Page</h3>
     <ul class="this-page-menu">
@@ -108,7 +108,7 @@ <h3>Navigation</h3>
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="modules.html" title="placekey"
+          <a href="modules.html" title="Placekey"
              >next</a> |</li>
         <li class="nav-item nav-item-0"><a href="#">placekey 0.0.1 documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Placekey-py documentation</a></li> 

diff --git a/docs/modules.html b/docs/modules.html
@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>placekey &#8212; placekey 0.0.1 documentation</title>
+    <title>Placekey &#8212; placekey 0.0.1 documentation</title>
     <link rel="stylesheet" href="_static/nature.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@@ -15,7 +15,7 @@
     <script src="_static/language_data.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="placekey package" href="placekey.html" />
+    <link rel="next" title="Submodules" href="placekey.html" />
     <link rel="prev" title="Placekey-py documentation" href="index.html" /> 
   </head><body>
     <div class="related" role="navigation" aria-label="related navigation">
@@ -28,13 +28,13 @@ <h3>Navigation</h3>
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="placekey.html" title="placekey package"
+          <a href="placekey.html" title="Submodules"
              accesskey="N">next</a> |</li>
         <li class="right" >
           <a href="index.html" title="Placekey-py documentation"
              accesskey="P">previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="index.html">placekey 0.0.1 documentation</a> &#187;</li>
-        <li class="nav-item nav-item-this"><a href="">placekey</a></li> 
+        <li class="nav-item nav-item-this"><a href="">Placekey</a></li> 
       </ul>
     </div>  
 
@@ -44,11 +44,12 @@ <h3>Navigation</h3>
           <div class="body" role="main">
 
   <div class="section" id="placekey">
-<h1>placekey<a class="headerlink" href="#placekey" title="Permalink to this headline">¶</a></h1>
+<h1>Placekey<a class="headerlink" href="#placekey" title="Permalink to this headline">¶</a></h1>
 <div class="toctree-wrapper compound">
 <ul>
-<li class="toctree-l1"><a class="reference internal" href="placekey.html">placekey package</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="placekey.html#module-placekey.placekey">placekey.placekey module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="placekey.html">Submodules</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="placekey.html#module-placekey.api">placekey.api</a></li>
+<li class="toctree-l2"><a class="reference internal" href="placekey.html#module-placekey.placekey">placekey.placekey</a></li>
 </ul>
 </li>
 </ul>
@@ -67,7 +68,7 @@ <h4>Previous topic</h4>
                         title="previous chapter">Placekey-py documentation</a></p>
   <h4>Next topic</h4>
   <p class="topless"><a href="placekey.html"
-                        title="next chapter">placekey package</a></p>
+                        title="next chapter">Submodules</a></p>
   <div role="note" aria-label="source link">
     <h3>This Page</h3>
     <ul class="this-page-menu">
@@ -99,13 +100,13 @@ <h3>Navigation</h3>
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="placekey.html" title="placekey package"
+          <a href="placekey.html" title="Submodules"
              >next</a> |</li>
         <li class="right" >
           <a href="index.html" title="Placekey-py documentation"
              >previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="index.html">placekey 0.0.1 documentation</a> &#187;</li>
-        <li class="nav-item nav-item-this"><a href="">placekey</a></li> 
+        <li class="nav-item nav-item-this"><a href="">Placekey</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">

diff --git a/docs/objects.inv b/docs/objects.inv