[V2] Add node APIs and clean up packaging (#182)

* [V2] Add node APIs and clean up packaging

* clean up

* update

* fix

* return value typing

* resolve comments

Author: shifucun

.github/ISSUE_TEMPLATE/python-api-v1-0-0-feedback.md

@@ -0,0 +1,41 @@
+# Data Commons Python API
+
+This is a Python library for accessing data in the Data Commons Graph.
+
+> See also: [Data Commons Pandas API](../datacommons_pandas/README.md).
+
+To get started, install this package from pip.
+
+```bash
+pip install datacommons
+```
+
+Once the package is installed, import `datacommons`.
+
+```python
+import datacommons as dc
+```
+
+For more detail on getting started with the API, please visit our
+[API Overview](https://docs.datacommons.org/api/).
+
+When you are ready to use the API, you can refer to `examples` for
+examples on how to use this package to perform various tasks. More tutorials and
+documentation can be found on our [tutorials page](https://docs.datacommons.org/tutorials/)!
+
+## About Data Commons
+
+[Data Commons](https://datacommons.org/) is an open knowledge repository that
+provides a unified view across multiple public data sets and statistics. You can
+view what [datasets](https://datacommons.org/datasets) are currently ingested
+and browse the graph using our [browser](https://datacommons.org/browser).
+
+## License
+
+Apache 2.0
+
+## Support
+
+For general questions or issues about the API, please open an issue on our
+[issues](https://github.com/google/datacommons/issues) page. For all other
+questions, please send an email to `[email protected]`.

README.md

@@ -29,5 +29,5 @@
 from datacommons.places import get_places_in, get_related_places, get_stats
 from datacommons.stat_vars import get_stat_value, get_stat_series, get_stat_all
 
-# Other utilities
-from datacommons.utils import set_api_key
+from datacommons.key import set_api_key
+from datacommons.node import properties, property_values, triples

datacommons/README.md

@@ -0,0 +1,28 @@
+# Copyright 2022 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+""" API key related functions.
+"""
+
+import os
+
+# Environment variable for API key.
+_KEY_ENV = 'DC_API_KEY'
+
+
+def set_api_key(api_key):
+    os.environ[_KEY_ENV] = api_key
+
+
+def get_api_key():
+    return os.environ.get(_KEY_ENV, '')

datacommons/__init__.py

@@ -0,0 +1,91 @@
+# Copyright 2022 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+""" API to request node information.
+"""
+
+from typing import Dict, List
+
+from datacommons.requests import _post
+from datacommons.utils import _get_direction
+
+
+def properties(nodes: List[str], is_out: bool = True) -> Dict[str, List[str]]:
+    """Retrieves all the properties for a list of nodes.
+
+    Note this only returns the property labels, not the values.
+    Args:
+        nodes: List of DCIDs.
+        is_out: Whether to return out going properties.
+    Returns:
+        A dict keyed by node DCID, with the values being a list of properties
+        for the queried node.
+    """
+    resp = _post(f'/v1/bulk/properties/{_get_direction(is_out)}', {
+        'nodes': nodes,
+    })
+    result = {}
+    for item in resp.get('data', []):
+        node, properties = item['node'], item.get('properties', [])
+        result[node] = properties
+    return result
+
+
+def property_values(nodes: List[str],
+                    property: str,
+                    is_out: bool = True) -> Dict[str, List[str]]:
+    """Retrieves the property values for a list of nodes.
+    Args:
+        nodes: List of DCIDs.
+        property: The property label to query for.
+        is_out: Whether the property is out going.
+    Returns:
+        A dict keyed by node DCID, with the values being a list of values
+        for the queried property.
+    """
+    resp = _post(f'/v1/bulk/property/values/{_get_direction(is_out)}', {
+        'nodes': nodes,
+        'property': property,
+    })
+    result = {}
+    for item in resp.get('data', []):
+        node, values = item['node'], item.get('values', [])
+        result[node] = []
+        for v in values:
+            if 'dcid' in v:
+                result[node].append(v['dcid'])
+            else:
+                result[node].append(v['value'])
+    return result
+
+
+def triples(nodes: List[str],
+            is_out: bool = True) -> Dict[str, Dict[str, List[object]]]:
+    """Retrieves the triples for a node.
+    Args:
+        nodes: List of DCIDs.
+        is_out: Whether the returned property is out going for the queried
+            nodes.
+    Returns:
+        A two level dict keyed by node DCID, then by the arc property, with
+        a list of values or DCIDs.
+    """
+    resp = _post(f'/v1/bulk/triples/{_get_direction(is_out)}',
+                 data={'nodes': nodes})
+    result = {}
+    for item in resp.get('data', []):
+        node, triples = item['node'], item.get('triples', {})
+        result[node] = {}
+        for property, other_nodes in triples.items():
+            result[node][property] = other_nodes.get('nodes', [])
+    return result

datacommons/key.py

@@ -0,0 +1,41 @@
+# Copyright 2022 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+""" Send http requests to Data Commons REST API endpoints.
+"""
+
+import requests
+from typing import Dict
+
+import datacommons.key as key
+
+# REST API endpoint root
+_API_ROOT = "https://api.datacommons.org"
+
+
+def _post(path: str, data={}) -> Dict:
+    url = _API_ROOT + path
+    headers = {'Content-Type': 'application/json'}
+    api_key = key.get_api_key()
+    if api_key:
+        headers['x-api-key'] = api_key
+    try:
+        resp = requests.post(url, json=data, headers=headers)
+        if resp.status_code != 200:
+            raise Exception(
+                f'{resp.status_code}: {resp.reason}\n{resp.json()["message"]}')
+        return resp.json()
+    except requests.exceptions.Timeout:
+        raise Exception('Data request timed out, please try again.')
+    except requests.exceptions.RequestException as e:
+        raise e