Add a new method to get related places. (#113)

* Add a new method to get related places.

* fix indents

Author: Spaceenter

datacommons/__init__.py

@@ -17,7 +17,7 @@
 
 # Data Commons Python Client API
 from datacommons.core import get_property_labels, get_property_values, get_triples
-from datacommons.places import get_places_in
+from datacommons.places import get_places_in, get_related_places
 from datacommons.populations import get_populations, get_observations, get_pop_obs, get_place_obs
 
 # Other utilities

datacommons/examples/places.py

@@ -4,7 +4,7 @@
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
@@ -22,6 +22,7 @@
 
 import datacommons as dc
 
+
 def main():
   # Create a list of dcids for Santa Clara and Montgomery County.
   sc, mc = 'geoId/06085', 'geoId/24031'
@@ -39,5 +40,12 @@ def main():
     for dcid in tracts[mc][:10]:
       print('  - {}'.format(dcid))
 
+  # Get related places.
+  print('Get related places')
+  related_places = dc.get_related_places(['geoId/06085'], 'Person',
+      {'age': "Years21To64", "gender": "Female"}, 'count', '')
+  print(related_places)
+
+
 if __name__ == '__main__':
   main()

datacommons/places.py

@@ -4,7 +4,7 @@
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
@@ -27,20 +27,20 @@
 
 def get_places_in(dcids, place_type):
   """ Returns :obj:`Place`s contained in :code:`dcids` of type
-      :code:`place_type`.
+    :code:`place_type`.
 
   Args:
     dcids (:obj:`iterable` of :obj:`str`): Dcids to get contained in places.
     place_type (:obj:`str`): The type of places contained in the given dcids to
-      filter by.
+    filter by.
 
   Returns:
     The returned :obj:`Place`'s are formatted as a :obj:`dict` from a given
     dcid to a list of places identified by dcids of the given `place_type`.
 
   Raises:
     ValueError: If the payload returned by the Data Commons REST API is
-      malformed.
+    malformed.
 
   Examples:
     We would like to get all Counties contained in
@@ -49,15 +49,15 @@ def get_places_in(dcids, place_type):
 
     >>> get_places_in(["geoId/06"], "County")
     {
-      'geoId/06': [
-        'geoId/06041',
-        'geoId/06089',
-        'geoId/06015',
-        'geoId/06023',
-        'geoId/06067',
-        ...
-        # and 53 more
-      ]
+    'geoId/06': [
+      'geoId/06041',
+      'geoId/06089',
+      'geoId/06015',
+      'geoId/06023',
+      'geoId/06067',
+      ...
+      # and 53 more
+    ]
     }
   """
   dcids = list(dcids)
@@ -70,3 +70,69 @@ def get_places_in(dcids, place_type):
   # Create the results and format it appropriately
   result = utils._format_expand_payload(payload, 'place', must_exist=dcids)
   return result
+
+
+def get_related_places(dcids, population_type, constraining_properties={},
+             measured_prop='count',
+             stat_type='measured', within_place='',
+             per_capita=False, same_place_type=False):
+  """ Returns :obj:`Place`s related to :code:`dcids` for the given constraints.
+
+  Args:
+    dcids (:obj:`iterable` of :obj:`str`): Dcids to get contained in places.
+    population_type (:obj:`str`): The type of statistical population.
+    constraining_properties (:obj:`map` from :obj:`str` to :obj:`str`, optional):
+    A map from constraining property to the value that the
+    :obj:`StatisticalPopulation` should be constrained by.
+    measured_property (:obj:`str`): The measured property.
+    stat_type (:obj:`str`): The statistical type for the observation.
+    within_place(:obj:`str`): Optional, the place that all the related places
+    are contained in.
+    per_capita(:obj:`bool`): Optional, whether to take into account
+    `PerCapita` when compute the relatedness.
+    same_place_type(:obj:`bool`): Optional, whether to require all the
+    related places under the same ancestor place.
+
+  Returns:
+    The returned :obj:`Place`'s are formatted as a :obj:`dict` from a given
+    dcid to a list of related places for the given constraints.
+
+  Raises:
+    ValueError: If the payload returned by the Data Commons REST API is
+    malformed.
+
+  Examples:
+    We would like to get all related places of
+    `Santa Clara county <https://browser.datacommons.org/kg?dcid=geoId/06085>`
+    Specifying the :code:`dcids` as a :obj:`list` result in the following.
+
+    >>> get_places_in(["geoId/06"], "Person", {
+    "age": "Years21To64",
+    "gender": "Female"
+    }, "count", "measured")
+    {
+    'geoId/06085': [
+      'geoId/06041',
+      'geoId/06089',
+      'geoId/06015',
+      'geoId/06023',
+    ]
+    }
+  """
+  dcids = list(dcids)
+  url = utils._API_ROOT + utils._API_ENDPOINTS['get_related_places']
+  pvs = []
+  for p in constraining_properties:
+    pvs.append({'property': p, 'value': constraining_properties[p]})
+  req_json = {
+    'dcids': dcids,
+    'populationType': population_type,
+    'pvs': pvs,
+    'measuredProperty': measured_prop,
+    'statType': '',  # TODO: Set to stat_type when having it in BT data.
+    'withinPlace': within_place,
+    'perCapita': per_capita,
+    'samePlaceType': same_place_type,
+  }
+  payload = utils._send_request(url, req_json=req_json)
+  return payload

datacommons/utils.py

@@ -42,6 +42,7 @@
   'get_property_values': '/node/property-values',
   'get_triples': '/node/triples',
   'get_places_in': '/node/places-in',
+  'get_related_places': '/node/related-places',
   'get_populations': '/node/populations',
   'get_observations': '/node/observations',
   'get_pop_obs': '/bulk/pop-obs',