Entity mapping endpoint usage and examples

Author: Dario Varotto

README.md

@@ -88,6 +88,39 @@ for record in ds.request_realtime():
 
 The Result object takes care of converting the various fields to the appropriate type, so `record.timestamp_utc` will be a `datetime`
 
+### Entity mapping
+
+The entity mapping endpoint allow you to find the RP_ENTITY_ID mapped to your universe of entities.
+
+```python
+universe = [
+	"RavenPack",
+	{'ticker': 'AAPL'},
+	'California USA',
+	{  # Amazon, specifying various fields
+		"client_id": "12345-A",
+		"date": "2017-01-01",
+		"name": "Amazon Inc.",
+		"entity_type": "COMP",
+		"isin": "US0231351067",
+		"cusip": "023135106",
+		"sedol": "B58WM62",
+		"listing": "XNAS:AMZN"
+	},
+	
+]
+mapping = api.get_entity_mapping(universe)
+
+# in this case we match everything
+assert len(mapping.matched) == len(universe)
+assert [m.name for m in mapping.matched] == [
+	"RavenPack International S.L.",
+	"Apple Inc.",
+	"California, U.S.",
+	"Amazon.com Inc."
+]
+```
+
 ### Entity reference
 
 The entity reference endpoint give you all the available information for an Entity given the RP_ENTITY_ID

ravenpackapi/core.py

@@ -7,6 +7,7 @@
 from ravenpackapi import Dataset
 from ravenpackapi.exceptions import APIException
 from ravenpackapi.models.dataset_list import DatasetList
+from ravenpackapi.models.mapping import RPMappingResults
 from ravenpackapi.models.reference import RpEntityReference
 from ravenpackapi.models.results import Results
 from ravenpackapi.util import to_curl
@@ -42,7 +43,10 @@ def headers(self):
                 }
 
     def request(self, endpoint, data=None, params=None, method='get'):
-        assert method in _VALID_METHODS, 'Method {used} not accepted. Please use {valid_methods}'
+        assert method in _VALID_METHODS, \
+            'Method {used} not accepted. Please choose one of {valid_methods}'.format(
+                used=method, valid_methods=", ".join(_VALID_METHODS)
+            )
         logger.debug("Request to %s" % endpoint)
         requests_call = getattr(requests, method)
         logger.debug("Request {method} to {endpoint}".format(method=method,
@@ -125,3 +129,14 @@ def get_entity_reference(self, rp_entity_id):
         )
         data = response.json()
         return RpEntityReference(rp_entity_id, data)
+
+    def get_entity_mapping(self, identifiers):
+        response = self.request(
+            endpoint="/entity-mapping",
+            method='post',
+            data={
+                "identifiers": identifiers
+            },
+        )
+        data = response.json()
+        return RPMappingResults(data)

ravenpackapi/examples/query_entity_mapping.py

@@ -0,0 +1,25 @@
+from ravenpackapi import RPApi
+
+
+class TestEntityMapping(object):
+    api = RPApi()
+
+    def test_matching_entity_mapping(self):
+        entities = [{'ticker': 'AAPL', 'name': 'Apple Inc.'},
+                    {'ticker': 'JPM'},
+                    {'listing': 'XNYS:DVN'}]
+        api = self.api
+        mapping = api.get_entity_mapping(entities)
+        assert not mapping.errors
+        assert len(mapping.matched) == len(mapping.submitted) == 3
+
+        # let's get the first mapped entities
+        rp_entity_ids = [match.id for match in mapping.matched]
+        assert rp_entity_ids == ['D8442A', '619882', '14BA06']
+
+    def test_mismatch_mapping(self):
+        entities = ["unknown!"]
+        api = self.api
+        mapping = api.get_entity_mapping(entities)
+        rp_entity_ids = [match.id for match in mapping.matched]
+        assert rp_entity_ids == []

ravenpackapi/models/mapping.py

@@ -0,0 +1,25 @@
+class RPMappingResults(object):
+    def __init__(self, data):
+        self.errors = []
+        self.matched = []
+        self.submitted = []
+        for mapping in data['identifiers_mapped']:
+            match = RPMappingMatch(mapping)
+            self.submitted.append(match)
+            if match.errors:
+                self.errors.append(match)
+            else:
+                self.matched.append(match)
+
+
+class RPMappingMatch(object):
+    def __init__(self, data):
+        self.request = data['request_data']
+        self.errors = data['errors']
+        if not self.errors:
+            self.candidates = data['rp_entities']
+            # let's put the best candidate data on the obj for convenience
+            best_match = self.candidates[0]
+            self.id = best_match['rp_entity_id']
+            self.name = best_match['rp_entity_name']
+            self.type = best_match['rp_entity_type']

ravenpackapi/tests/query_entity_mapping.py

@@ -0,0 +1,52 @@
+from ravenpackapi import RPApi
+
+
+class TestEntityMapping(object):
+    api = RPApi()
+
+    def test_matching_entity_mapping(self):
+        entities = [{'ticker': 'AAPL', 'name': 'Apple Inc.'},
+                    {'ticker': 'JPM'},
+                    {'listing': 'XNYS:DVN'}]
+        mapping = self.api.get_entity_mapping(entities)
+        assert not mapping.errors
+        assert len(mapping.matched) == len(mapping.submitted) == 3
+
+        # let's get the first mapped entities
+        rp_entity_ids = [match.id for match in mapping.matched]
+        assert rp_entity_ids == ['D8442A', '619882', '14BA06']
+
+    def test_mismatch_mapping(self):
+        entities = ["unknown!"]
+        mapping = self.api.get_entity_mapping(entities)
+        rp_entity_ids = [match.id for match in mapping.matched]
+        assert rp_entity_ids == []
+
+    def test_mapping_example(self):
+        invalid_entity_request = "Unknown entity specified"
+        universe = [
+            "RavenPack",
+            {'ticker': 'AAPL'},
+            'California USA',
+            {  # Amazon, specifying various fields
+                "client_id": "12345-A",
+                "date": "2017-01-01",
+                "name": "Amazon Inc.",
+                "entity_type": "COMP",
+                "isin": "US0231351067",
+                "cusip": "023135106",
+                "sedol": "B58WM62",
+                "listing": "XNAS:AMZN"
+            },
+            invalid_entity_request
+        ]
+        mapping = self.api.get_entity_mapping(universe)
+        assert len(mapping.matched) == 4
+        assert [m.name for m in mapping.matched] == [
+            "RavenPack International S.L.",
+            "Apple Inc.",
+            "California, U.S.",
+            "Amazon.com Inc."
+        ]
+        assert len(mapping.errors) == 1
+        assert mapping.errors[0].request == invalid_entity_request