fix: Reference now returns dict, fixes #69

tests/conversions/test_conversions.py

@@ -12,7 +12,7 @@ def test_convert_to_geography_ids(self):
         rotterdam_id = (
             "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e"
         )
-        rotterdam_name = Geographies().reference(rotterdam_id)[0]["name"]
+        rotterdam_name = Geographies().reference(rotterdam_id)["name"]
 
         result = convert_to_geography_ids([rotterdam_name])
 

tests/endpoints/test_products_real.py

@@ -75,4 +75,4 @@ def test_lookup_crude(self):
             "6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653"
         )
 
-        assert result[0]["name"] == "Crude"
+        assert result["name"] == "Crude"

tests/endpoints/test_reference_endpoints_real.py

@@ -0,0 +1,18 @@
+from tests.testcases import TestCaseUsingRealAPI
+from docs.utils import to_markdown
+from vortexasdk import Geographies
+
+
+class TestGeographiesReal(TestCaseUsingRealAPI):
+    def test_search(self):
+        geographies = Geographies().search(term=["Liverpool", "Southampton"])
+        names = [g["name"] for g in geographies]
+
+        assert "Liverpool [GB]" in names
+
+    def test_search_to_df(self):
+        geographies = (
+            Geographies().search(term=["Liverpool", "Southampton"]).to_df()
+        )
+
+        print(to_markdown(geographies))

tests/mock_client.py

@@ -32,8 +32,9 @@ class MockVortexaClient(AbstractVortexaClient):
         VESSEL_MOVEMENTS_RESOURCE: example_vessel_movements,
     }
 
-    def get_reference(self, resource: str, id: ID) -> str:
-        return ""
+    def get_reference(self, resource: str, id: ID) -> List[Dict]:
+        entities = MockVortexaClient._results[resource]
+        return [e for e in entities if e["id"] == id]
 
     def search(self, resource: str, **data) -> List:
         return MockVortexaClient._results[resource]

vortexasdk/client.py

@@ -2,7 +2,7 @@
 import functools
 import os
 from multiprocessing.pool import ThreadPool
-from typing import List
+from typing import Dict, List
 
 from requests import Response
 
@@ -23,7 +23,7 @@ class VortexaClient(AbstractVortexaClient):
     def __init__(self, **kwargs):
         self.api_key = kwargs["api_key"]
 
-    def get_reference(self, resource: str, id: ID) -> str:
+    def get_reference(self, resource: str, id: ID) -> List[Dict]:
         """Lookup reference data."""
         url = self._create_url(f"{resource}/{id}")
         response = retry_get(url)
@@ -91,7 +91,7 @@ def _send_post_request(url, payload, size, offset):
     return response
 
 
-def _handle_response(response: Response, payload=None) -> dict:
+def _handle_response(response: Response, payload=None) -> Dict:
     if response.ok:
         return response.json()
     else:

vortexasdk/endpoints/corporations.py

@@ -1,5 +1,5 @@
 """Corporations Endpoint."""
-from typing import List, Union
+from typing import List, Union, Dict
 
 from vortexasdk.api import ID
 from vortexasdk.endpoints.corporations_result import CorporationsResult
@@ -55,7 +55,7 @@ def search(self, term: Union[str, List[str]] = None) -> CorporationsResult:
         params = convert_values_to_list({"term": term})
         return CorporationsResult(super().search(**params))
 
-    def reference(self, id: ID):
+    def reference(self, id: ID) -> Dict:
         """
         Perform a corporation lookup.
 

vortexasdk/endpoints/geographies.py

@@ -1,5 +1,5 @@
 """Geographies Endpoint."""
-from typing import List, Union
+from typing import List, Union, Dict
 
 from vortexasdk.api import ID
 from vortexasdk.endpoints.endpoints import GEOGRAPHIES_REFERENCE
@@ -51,7 +51,7 @@ def search(self, term: Union[str, List[str]] = None) -> GeographyResult:
         params = convert_values_to_list({"term": term})
         return GeographyResult(super().search(**params))
 
-    def reference(self, id: ID):
+    def reference(self, id: ID) -> Dict:
         """
         Perform a geography lookup.
 

vortexasdk/endpoints/products.py

@@ -1,5 +1,5 @@
 """Products Endpoint."""
-from typing import List, Union
+from typing import List, Union, Dict
 
 from vortexasdk.api.shared_types import ID
 from vortexasdk.endpoints.endpoints import PRODUCTS_REFERENCE
@@ -67,7 +67,7 @@ def search(
 
         return ProductResult(super().search(**search_params))
 
-    def reference(self, id: ID):
+    def reference(self, id: ID) -> Dict:
         """
         Perform a product lookup.
 

vortexasdk/endpoints/vessels.py

@@ -1,5 +1,5 @@
 """Vessels Endpoint."""
-from typing import List, Union
+from typing import List, Union, Dict
 
 from vortexasdk.api.id import ID
 from vortexasdk.conversions import convert_to_product_ids
@@ -85,7 +85,7 @@ def search(
 
         return VesselsResult(super().search(**search_params))
 
-    def reference(self, id: ID):
+    def reference(self, id: ID) -> Dict:
         """
         Perform a vessel lookup.
 

vortexasdk/exceptions.py

@@ -0,0 +1,4 @@
+class InvalidAPIDataResponseException(Exception):
+    """Vortexa API returned Faulty Data, contact support."""
+
+    pass

vortexasdk/operations.py

@@ -1,7 +1,8 @@
-from typing import List
+from typing import Dict, List
 
 from vortexasdk.api.id import ID
 from vortexasdk.client import default_client
+from vortexasdk.exceptions import InvalidAPIDataResponseException
 from vortexasdk.logger import get_logger
 
 logger = get_logger(__name__)
@@ -20,7 +21,7 @@ def __init__(self, resource):
         """
         self._resource = resource
 
-    def reference(self, id: ID):
+    def reference(self, id: ID) -> Dict:
         """
         Lookup reference data using ID.
 
@@ -38,7 +39,16 @@ def reference(self, id: ID):
         logger.info(
             f"Looking up {self.__class__.__name__} reference data with id: {id}"
         )
-        return default_client().get_reference(self._resource, id)
+
+        data = default_client().get_reference(self._resource, id)
+
+        assert len(data) <= 1, InvalidAPIDataResponseException(
+            f"Server error: more than one record returned matching ID {id}"
+        )
+        try:
+            return data[0]
+        except IndexError:
+            return {}
 
 
 class Search: