diff --git a/README.md b/README.md
index 4510f976ec1124b666ce2f691af6df24ad3ed7fd..d65502114927d706d97cb963d5fd308e4e8d881f 100644
--- a/README.md
+++ b/README.md
@@ -74,3 +74,29 @@ Cookie file - https://www.dns.cam.ac.uk/ipreg/api/
 
 Download cookie - https://jackdaw.cam.ac.uk/ipreg/download-cookie
 
+
+# Usage
+
+```
+>>> import ipreg
+>>> api_client = ipreg.IPRegApi(cookie_file='cookie-jackdaw-dev.txt')
+>>> api_client.get_list_ops_by_subnet('192.168.1.0')
+[{'address': '192.168.1.15', 'mzone': 'MYMZONE', 'lan': 'MYLAND', 'name': 'comp58.mydomain.test.cam.ac.uk' ...},{'address': '192.168.1.27', 'mzone': 'MYMZONE', 'lan': 'MYLAND', 'name': 'comp66.mydomain.test.cam.ac.uk' ...}]
+>>> api_client.get_ip_info('192.168.1.15')
+{'address': '131.111.92.166', 'mzone': 'MYMZONE', 'lan': 'MYLAND', 'name': 'comp58.mydomain.test.cam.ac.uk'...
+```
+
+The previous example shows an interactive session that pulls back a whole subnet info and then a specific
+ip address detail.
+
+```python
+import ipreg
+api_client = ipreg.IPRegApi(cookie_file='/path/to/my/cookie-jackdaw.txt', cache_dir='/path/to/my/cache/')
+
+fqdn = 'comp58.mydomain.test.cam.ac.uk'
+ip = '192.168.1.15'
+
+ip_info = api_client.get_ip_info(ip)
+hostname_info = api_client.get_hostname_info(fqdn)
+```
+
diff --git a/tests/generate_mock_data.py b/tests/generate_mock_data.py
new file mode 100644
index 0000000000000000000000000000000000000000..8754c8425ded5ae594ce265c410da7bf960bad9e
--- /dev/null
+++ b/tests/generate_mock_data.py
@@ -0,0 +1,15 @@
+import tests.mock_data
+
+mock_ipreg_data = tests.mock_data.ipreg.IPReg()
+
+subnet = '192.168.12.0'
+domain = 'mydomain.test.cam.ac.uk'
+
+data = mock_ipreg_data.list_ops_by_list_subnet(subnet, domain)
+print(data['text_response'])
+
+data = mock_ipreg_data.xlist_ops_by_list_domain(domain, subnet)
+print(data['text_response'])
+
+# with open('ipreg--mock_list_subnet.txt', 'w') as f:
+#     f.write(text_response)
diff --git a/tests/mock_data/ipreg.py b/tests/mock_data/ipreg.py
index adf6967ff122ef11019728dc0adabf73e32a5ec5..bf3e2a3890e1efcf1c6ef51d729fbc03638cc350 100644
--- a/tests/mock_data/ipreg.py
+++ b/tests/mock_data/ipreg.py
@@ -1,3 +1,8 @@
+"""IPReg Mock Data generator
+
+
+"""
+
 
 class IPReg:
 
@@ -16,10 +21,21 @@ class IPReg:
             'review_date'
         ]
 
+        self.xlist_box_list_domain_headers = [
+            'name',
+            'equipment',
+            'location',
+            'owner',
+            'sysadmin',
+            'end_user',
+            'remarks',
+            'review_date',
+            'addresses'
+        ]
+
         self.default_line_break = "\r\n"
         self.default_mzone = "MYMZONE"
         self.default_lan = "MYLAN"
-        self.default_domain = "mydomain.cam.ac.uk"
 
         self.ips = [13, 15, 27, 36, 51]
         self.hostnames = ['comp123', 'comp58', 'comp66', 'comp69', 'comp89', 'comp93']
@@ -34,23 +50,61 @@ class IPReg:
             'Sidney Applebaum'
         ]
 
-    def get_all_boxes(self, subnet):
-
+    def get_subnet_base(self, subnet):
         ip_parts = subnet.split(".")
         if len(ip_parts) != 4:
             raise Exception("Invalid IP: " + subnet)
 
         del(ip_parts[3])
         subnet_base = ".".join(ip_parts)
+        return subnet_base
+
+    def xlist_ops_by_list_domain(self, domain, subnet):
+        request_url = '/ipreg/xlist_ops?do_it=list_domain&domain=' + \
+                         domain + \
+                         '&object_type=box&record_separator=CRLF'
+
+        boxes = []
+        for i in range(0, 5):
+            ip = self.get_subnet_base(subnet) + "." + str(self.ips[i])
+            item = [
+                self.hostnames[i] + '.' + domain,
+                self.equipments[i],
+                self.locations[i],
+                self.owners[i],
+                '',
+                self.users[i],
+                '',
+                '',
+                ip
+            ]
+            boxes.append(item)
+
+        text_response = "\t".join(self.xlist_box_list_domain_headers)
+        text_response = text_response + self.default_line_break
+        for box in boxes:
+            text_response = text_response + "\t".join(box)
+            text_response = text_response + self.default_line_break
+
+        return {
+            'url': request_url,
+            'text_response': text_response
+        }
+
+    def list_ops_by_list_subnet(self, subnet, domain):
+
+        request_url = '/ipreg/list_ops?do_it=list_subnet&subnet_base=' + \
+                             subnet + \
+                             '&record_separator=CRLF'
 
         boxes = []
         for i in range(0, 5):
-            ip = subnet_base + "." + str(self.ips[i])
+            ip = self.get_subnet_base(subnet) + "." + str(self.ips[i])
             item = [
                 ip,
                 self.default_mzone,
                 self.default_lan,
-                self.hostnames[i] + '.' + self.default_domain,
+                self.hostnames[i] + '.' + domain,
                 self.equipments[i],
                 self.locations[i],
                 self.owners[i],
@@ -67,4 +121,7 @@ class IPReg:
             text_response = text_response + "\t".join(box)
             text_response = text_response + self.default_line_break
 
-        return text_response
+        return {
+            'url': request_url,
+            'text_response': text_response
+        }
diff --git a/tests/test_api.py b/tests/test_api.py
index 1cf532777d6c80d96673ab037659a0411df63db5..f60132987c354f4ccae9267e48a6eb55ae4d33ae 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -11,12 +11,15 @@ import ipreg
 def setup_module(module):
     """ setup any state specific to the execution of the given module."""
 
+    # The testing cache directory needs to exist
     current_directory = os.getcwd()
     final_directory = os.path.join(current_directory, r'cache-tests')
     pytest.cache_directory = final_directory
     if not os.path.exists(final_directory):
         os.makedirs(final_directory)
 
+    # A fake cookie is needed to ensure that the cookie validation
+    # part of the API will pass.
     pytest.cookie_file_name = 'cookie-jackdaw-gen-test.txt'
     with open(pytest.cookie_file_name, 'w') as f:
         cookie_parts = [
@@ -35,21 +38,21 @@ def teardown_module(module):
     """ teardown any state that was previously setup with a setup_module
     method.
     """
+
+    # Remove the cookies and cache directory
     os.rmdir(pytest.cache_directory)
     os.remove(pytest.cookie_file_name)
 
 
 def test_get_ip_info(requests_mock):
 
+    domain = 'mydomain.test.cam.ac.uk'
     subnet = '192.168.1.0'
-    subnet_request_url = '/ipreg/list_ops?do_it=list_subnet&subnet_base=' + \
-                         subnet + \
-                         '&record_separator=CRLF'
 
     # Register mock data against url
     mock_ipreg_data = tests.mock_data.ipreg.IPReg()  # Generates jackdaw ipreg responses
-    text_response = mock_ipreg_data.get_all_boxes(subnet)
-    requests_mock.get(subnet_request_url, text=text_response)
+    data = mock_ipreg_data.list_ops_by_list_subnet(subnet, domain)
+    requests_mock.get(data['url'], text=data['text_response'])
 
     api_client = ipreg.IPRegApi(cookie_file=pytest.cookie_file_name)
 
@@ -57,3 +60,21 @@ def test_get_ip_info(requests_mock):
     ip_info = api_client.get_ip_info(ip)
 
     assert ip_info['address'] == ip
+
+
+def test_get_domain_info(requests_mock):
+
+    domain = 'mydomain.test.cam.ac.uk'
+    subnet = '192.168.1.0'
+
+    # Register mock data against url
+    mock_ipreg_data = tests.mock_data.ipreg.IPReg()  # Generates jackdaw ipreg responses
+    data = mock_ipreg_data.xlist_ops_by_list_domain(domain, subnet)
+    requests_mock.get(data['url'], text=data['text_response'])
+
+    api_client = ipreg.IPRegApi(cookie_file=pytest.cookie_file_name)
+
+    hostname = "comp66.mydomain.test.cam.ac.uk"
+    hostname_info = api_client.get_hostname_info(hostname)
+
+    assert hostname_info['name'] == hostname