├── tests
    ├── __init__.py
    ├── test_client.py
    └── test_endpoints.py
├── VERSION.txt
├── MANIFEST.in
├── .gitignore
├── bin
    ├── deploy
    ├── runtests.ps1
    ├── runtests
    └── Jenkinsfile
├── intrinio
    ├── __init__.py
    ├── client.py
    └── endpoints.py
├── requirements.txt
├── .travis.yml
├── tox.ini
├── Vagrantfile
├── Jenkinsfile
├── CHANGELOG.md
├── setup.py
├── LICENSE
└── README.md


/tests/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/VERSION.txt:
--------------------------------------------------------------------------------
1 | 0.2.1
2 | 


--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include *.txt *.md
2 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .*
2 | __pycache__
3 | *egg-info
4 | *.pyc
5 | dist
6 | build
7 | tmp
8 | 


--------------------------------------------------------------------------------
/bin/deploy:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 | 
3 | python setup.py sdist bdist_wheel
4 | twine upload dist/intrinio-*.tar.gz
5 | 
6 | 


--------------------------------------------------------------------------------
/intrinio/__init__.py:
--------------------------------------------------------------------------------
1 | from intrinio.client import username, password, get, get_page
2 | from intrinio.endpoints import *


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
 1 | requests==2.32.4
 2 | pandas==0.23.0
 3 | 
 4 | pytest==3.6.1
 5 | pytest-cov==2.5.1
 6 | pytest-watch==4.2.0
 7 | tox==3.0.0
 8 | detox==0.12
 9 | pypandoc==1.4
10 | rope==0.11.0
11 | twine==1.11.0
12 | 


--------------------------------------------------------------------------------
/bin/runtests.ps1:
--------------------------------------------------------------------------------
1 | mkdir -f -p tmp | Out-Null
2 | 
3 | py.test -rw --doctest-modules --junitxml=tmp/tests.xml --cov=intrinio --cov-report term-missing --cov-report xml:tmp/coverage.xml --cov-report html:tmp/coverage.html --ignore=setup.py .
4 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: python
 2 | python:
 3 | - '2.7'
 4 | - '3.6'
 5 | before_install:
 6 | - sudo apt-get -qq update
 7 | cache:
 8 |   directories:
 9 |   - $HOME/.cache/intrinio
10 | install: pip install -r requirements.txt
11 | script: bin/runtests
12 | 
13 | 


--------------------------------------------------------------------------------
/bin/runtests:
--------------------------------------------------------------------------------
 1 | #!/bin/bash
 2 | 
 3 | mkdir -p tmp
 4 | 
 5 | py.test -rw --doctest-modules \
 6 |         --junitxml=tmp/tests.xml \
 7 |         --cov=intrinio \
 8 |         --cov-report term-missing \
 9 |         --cov-report xml:tmp/coverage.xml \
10 |         --cov-report html:tmp/coverage.html \
11 |         --ignore=setup.py \
12 |         .
13 | 


--------------------------------------------------------------------------------
/tox.ini:
--------------------------------------------------------------------------------
 1 | # Tox (http://tox.testrun.org/) is a tool for running tests
 2 | # in multiple virtualenvs. This configuration file will run the
 3 | # test suite on all supported python versions. To use it, "pip install tox"
 4 | # and then run "tox" from this directory.
 5 | 
 6 | [tox]
 7 | envlist = py27, py36
 8 | 
 9 | [testenv]
10 | passenv = *
11 | commands = py.test
12 | deps =
13 |     -rrequirements.txt
14 | 
15 | 


--------------------------------------------------------------------------------
/Vagrantfile:
--------------------------------------------------------------------------------
 1 | # -*- mode: ruby -*-
 2 | # vi: set ft=ruby :
 3 | 
 4 | $PROVISION_SCRIPT = <<SCRIPT
 5 | apt update
 6 | apt install -y python-pandas python-pip ipython-notebook
 7 | 
 8 | # Intrinio authentication environment variables
 9 | tee "/etc/profile.d/intrinio-auth.sh" > "/dev/null" <<EOF
10 | export INTRINIO_USERNAME=#{ENV['INTRINIO_USERNAME']}
11 | export INTRINIO_PASSWORD=#{ENV['INTRINIO_PASSWORD']}
12 | EOF
13 | SCRIPT
14 | 
15 | Vagrant.configure("2") do |config|
16 |   config.vm.box = "bento/ubuntu-16.04"
17 |   config.vm.provision "shell", inline: $PROVISION_SCRIPT, run: "always"
18 | end
19 | 


--------------------------------------------------------------------------------
/Jenkinsfile:
--------------------------------------------------------------------------------
 1 | pipeline {
 2 |   agent {
 3 |     docker {
 4 |       image 'continuumio/anaconda3:5.1.0'
 5 |       args '-v $HOME/.cache/intrinio:/root/.cache/intrinio'
 6 |     }
 7 |   }
 8 | 
 9 |   stages {
10 |     stage('Build') {
11 |       steps {
12 |         sh 'pip install -r requirements.txt'
13 |       }
14 |     }
15 |     stage('Test') {
16 |       environment {
17 |         INTRINIO_USERNAME = credentials('intrinio-username')
18 |         INTRINIO_PASSWORD = credentials('intrinio-password')
19 |       }
20 |       steps {
21 |         sh './bin/runtests'
22 |       }
23 |     }
24 |   }
25 | 
26 |   post {
27 |     always {
28 |       junit 'tmp/**/*.xml'
29 |     }
30 |   }
31 | }
32 | 
33 | 


--------------------------------------------------------------------------------
/bin/Jenkinsfile:
--------------------------------------------------------------------------------
 1 | pipeline {
 2 |   agent {
 3 |     docker {
 4 |       image 'continuumio/anaconda3:5.1.0'
 5 |       args '-v $HOME/.cache/intrinio:/root/.cache/intrinio'
 6 |     }
 7 |   }
 8 | 
 9 |   stages {
10 |     stage('Build') {
11 |       steps {
12 |         sh 'pip install -r requirements.txt'
13 |       }
14 |     }
15 |     stage('Test') {
16 |       environment {
17 |         INTRINIO_USERNAME = credentials('intrinio-username')
18 |         INTRINIO_PASSWORD = credentials('intrinio-password')
19 |       }
20 |       steps {
21 |         sh './bin/runtests'
22 |       }
23 |     }
24 |   }
25 | 
26 |   post {
27 |     always {
28 |       junit 'tmp/**/*.xml'
29 |     }
30 |   }
31 | }
32 | 
33 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | 
 3 | ## 0.2.1 - 2018-03-24
 4 | 
 5 | * Fix sequence based indexes for multi-page queries
 6 | 
 7 | ## 0.2.0 - 2018-02-01
 8 | 
 9 | * Add stock screener endpoint: screener
10 | * Add disk cache to minimize API usage for tests.
11 | * Fix error when total pages are not available in API response
12 | 
13 | ## 0.1.18 - 2017-12-31
14 | 
15 | * Fix retrieving financials using TTM
16 | 
17 | ## 0.1.17 - 2017-09-28
18 | 
19 | * Add endpoints: financials and fundamentals
20 | 
21 | ## 0.1.16 - 2017-06-07
22 | 
23 | * Fix authentication instructions in README
24 | 
25 | ## 0.1.15 - 2017-02-05
26 | 
27 | * Fix ImportError of pypandoc
28 | 
29 | ## 0.1.14 - 2017-01-16
30 | 
31 | * Add get to retrieve whole datasets
32 | * Add get_page to retrieve datasets one page at a time
33 | * Add endpoints: companies, securities, indices, prices, news
34 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | import io
 2 | from setuptools import setup
 3 | 
 4 | # Version
 5 | version = open('VERSION.txt').read()
 6 | 
 7 | # Long description
 8 | try:
 9 |     import pypandoc
10 |     long_description = pypandoc.convert('README.md', 'rst')
11 |     long_description = long_description.replace("\r", "")
12 | except (OSError, ImportError):
13 |     print("Pandoc not found. Conversion of README.md to rst not available.")
14 |     with io.open('README.md', encoding="utf-8") as f:
15 |         long_description = f.read()
16 | 
17 | # Setup
18 | setup(name='intrinio',
19 |       version=version,
20 |       description='Intrinio API client',
21 |       long_description=long_description,
22 |       keywords=['intrinio', 'API', 'data', 'client', 'quant', 'finance'],
23 |       url='https://github.com/nhedlund/intrinio',
24 |       author='nhedlund',
25 |       license='MIT',
26 |       packages=['intrinio'],
27 |       zip_safe=False,
28 |       install_requires=[
29 |           'pandas >= 0.14',
30 |           'numpy >= 1.8',
31 |           'requests >= 2.7.0']
32 |       )
33 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2017 Niklas Hedlund
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/tests/test_client.py:
--------------------------------------------------------------------------------
 1 | import pandas as pd
 2 | import pytest
 3 | import intrinio
 4 | from requests import HTTPError
 5 | 
 6 | from intrinio.client import get, get_page, _query, _web_request, \
 7 |     _web_request_cached, get_page_size
 8 | 
 9 | intrinio.client.cache_enabled = True
10 | 
11 | def test_get_companies_data_with_query():
12 |     companies = get('companies', query='Cola')
13 |     assert len(companies) > 1
14 |     assert companies.name.str.contains('Cola').any()
15 | 
16 | 
17 | def test_get_companies_data_with_query_that_returns_many_pages():
18 |     companies = get('companies', query='Corp')
19 |     assert len(companies) > get_page_size('companies')
20 |     assert len(companies) > 300
21 |     assert companies.name.str.contains('Corp').any()
22 | 
23 | 
24 | def test_get_first_page_of_companies_data():
25 |     companies = get_page('companies')
26 |     assert isinstance(companies, pd.DataFrame)
27 |     assert len(companies) == get_page_size('companies')
28 |     assert companies.total_pages > 1
29 |     assert 'ticker' in companies.columns
30 |     assert 'cik' in companies.columns
31 |     assert 'lei' in companies.columns
32 |     assert 'name' in companies.columns
33 | 
34 | 
35 | def test_query_companies():
36 |     response = _query('companies')
37 |     assert isinstance(response, dict)
38 |     assert 'result_count' in response
39 |     assert 'page_size' in response
40 |     assert 'current_page' in response
41 |     assert 'total_pages' in response
42 | 
43 |     data = response['data']
44 |     assert isinstance(data, list)
45 |     assert isinstance(data[0], dict)
46 |     assert 'ticker' in data[0]
47 |     assert 'cik' in data[0]
48 |     assert 'lei' in data[0]
49 |     assert 'name' in data[0]
50 | 
51 | 
52 | def test_get_missing_endpoint():
53 |     with pytest.raises(HTTPError):
54 |         get('missing_endpoint')
55 | 
56 | 
57 | def test_query_search_engine():
58 |     response = _web_request('https://bing.com/search', {'q': 'summer'})
59 |     assert 'summer' in response
60 | 
61 | 
62 | def test_query_search_engine_cached():
63 |     response = _web_request_cached('https://bing.com/search', {'q': 'summer'})
64 |     assert 'summer' in response
65 | 
66 | 
67 | def test_get_page_size_with_defined_endpoint():
68 |     page_size = get_page_size('prices')
69 |     assert page_size == 50000
70 | 
71 | 
72 | def test_get_page_size_with_undefined_endpoint():
73 |     page_size = get_page_size('not-defined')
74 |     assert page_size == 250
75 | 


--------------------------------------------------------------------------------
/tests/test_endpoints.py:
--------------------------------------------------------------------------------
 1 | import intrinio
 2 | from intrinio.endpoints import *
 3 | 
 4 | intrinio.client.cache_enabled = True
 5 | 
 6 | def test_endpoint_companies_with_query():
 7 |     df = companies(query='Bank')
 8 |     assert len(df) > 10
 9 |     assert df.name.str.contains('Bank').any()
10 | 
11 | 
12 | def test_endpoint_companies_with_identifier():
13 |     df = companies('AAPL')
14 |     assert len(df) == 1
15 |     assert df.name.str.contains('Apple').any()
16 | 
17 | 
18 | def test_endpoint_securities_with_identifier():
19 |     df = securities('aapl')
20 |     assert len(df) == 1
21 |     assert df.security_name.str.contains('APPLE', case=False).any()
22 | 
23 | 
24 | def test_endpoint_indices_with_identifier():
25 |     df = indices('$spx')
26 |     assert len(df) == 1
27 | 
28 | 
29 | def test_endpoint_indices_with_type():
30 |     df = indices(type='Stock_Market')
31 |     assert len(df) > 1
32 | 
33 | 
34 | def test_endpoint_prices_with_descending_order():
35 |     df = prices('AAPL', start_date='2015-01-01')
36 |     assert 'date' not in df.columns
37 |     assert len(df) > 500
38 |     assert df.index[0] > df.index[1]
39 | 
40 | 
41 | def test_endpoint_prices_with_ascending_order():
42 |     df = prices('AAPL', start_date='2015-01-01', sort_order='asc')
43 |     assert 'date' not in df.columns
44 |     assert len(df) > 500
45 |     assert df.index[0] < df.index[1]
46 | 
47 | 
48 | def test_endpoint_news():
49 |     df = news('A')
50 |     assert len(df) > 200
51 |     assert df.summary.str.contains('Agilent', case=False).any()
52 | 
53 | 
54 | def test_endpoint_fundamentals():
55 |     df = fundamentals('AC')
56 |     assert len(df) >= 3
57 |     assert (df.fiscal_period == 'FY').all()
58 | 
59 | 
60 | def test_endpoint_financials():
61 |     df = financials('AC')
62 |     assert len(df) >= 3
63 |     assert (df.ebit != 0.0).any()
64 | 
65 | 
66 | def test_endpoint_financials_quarter_periods():
67 |     df = financials('AC', 'QTR')
68 |     assert len(df) >= 3
69 |     assert (df.ebit != 0.0).any()
70 | 
71 | 
72 | def test_endpoint_financials_period_with_first_quarter():
73 |     df = financials_period('AC', 2015, 'Q1')
74 |     assert len(df) == 1
75 |     assert df.ebit[0] > 2000000
76 |     assert df.ebit[0] < 3000000
77 | 
78 | 
79 | def test_endpoint_screener():
80 |     df = screener('pricetoearnings~gt~5')
81 |     assert len(df) >= 100
82 |     assert (df.pricetoearnings >= 10).any()
83 |     assert not (df.pricetoearnings < 5).any()
84 |     assert (df.ticker == 'AAPL').any()
85 | 


--------------------------------------------------------------------------------
/intrinio/client.py:
--------------------------------------------------------------------------------
  1 | """Get datasets from Intrinio API, either complete or one page at a time."""
  2 | import os
  3 | import logging
  4 | import json
  5 | import requests.sessions as sessions
  6 | import pandas as pd
  7 | import hashlib
  8 | import time
  9 | import codecs
 10 | 
 11 | username = os.getenv('INTRINIO_USERNAME')
 12 | password = os.getenv('INTRINIO_PASSWORD')
 13 | cache_enabled = (os.getenv('INTRINIO_CACHE', 'false') == 'true')
 14 | cache_directory = os.path.expanduser('~/.cache/intrinio')
 15 | cache_max_age = 3600 * 8
 16 | 
 17 | page_sizes = {
 18 |     'prices': 50000,
 19 |     'historical_data': 50000,
 20 |     'tags/standardized': 5000,
 21 |     'tags/reported': 5000,
 22 |     'tags/banks': 5000,
 23 |     'financials/standardized': 5000,
 24 |     'financials/reported': 5000,
 25 |     'financials/banks': 5000,
 26 | }
 27 | 
 28 | api_base_url = 'https://api.intrinio.com'
 29 | default_page_size = 250
 30 | log = logging.getLogger(__name__)
 31 | 
 32 | 
 33 | def get(endpoint, **parameters):
 34 |     """
 35 |     Get complete dataset from an endpoint using optional query parameters.
 36 | 
 37 |     Args:
 38 |         endpoint: Intrinio endpoint, for example: companies
 39 |         parameters: Optional query parameters
 40 | 
 41 |     Returns:
 42 |         Dataset as a Pandas DataFrame
 43 |     """
 44 |     page_number = 1
 45 |     dataset = pd.DataFrame()
 46 | 
 47 |     while True:
 48 |         page = get_page(endpoint, page_number, **parameters)
 49 |         dataset = pd.concat([dataset, page], ignore_index=True)
 50 | 
 51 |         if len(page) == 0 or page_number == page.total_pages:
 52 |             return dataset
 53 | 
 54 |         page_number += 1
 55 | 
 56 | 
 57 | def get_page(endpoint, page_number=1, page_size=None, **parameters):
 58 |     """
 59 |     Get a dataset page from an endpoint using optional query parameters.
 60 | 
 61 |     Args:
 62 |         endpoint: Intrinio endpoint, for example: companies
 63 |         page_number: Optional page number where 1 is the first page (default 1)
 64 |         page_size: Optional page size (default max page size for the endpoint)
 65 |         parameters: Optional query parameters
 66 | 
 67 |     Returns:
 68 |         Dataset page as a Pandas DataFrame with an additional total_pages
 69 |         attribute
 70 |     """
 71 |     response = _query(endpoint, page_number, page_size, **parameters)
 72 | 
 73 |     if 'data' in response:
 74 |         page = pd.DataFrame(response['data'])
 75 |         page.total_pages = response.get('total_pages', 1)
 76 |     else:
 77 |         page = pd.DataFrame([response])
 78 |         page.total_pages = 1
 79 | 
 80 |     return page
 81 | 
 82 | 
 83 | def _query(endpoint, page_number=1, page_size=None, **parameters):
 84 |     """
 85 |     Send a query request to Intrinio API for a dataset page including page
 86 |     count and other metadata using optional query parameters.
 87 | 
 88 |     Args:
 89 |         endpoint: Intrinio endpoint, for example: companies
 90 |         page_number: Optional page number where 1 is the first page (default 1)
 91 |         page_size: Optional page size (default max page size for the endpoint)
 92 |         parameters: Optional query parameters
 93 | 
 94 |     Returns:
 95 |         Intrinio endpoint response as a tree of dictionaries, values and lists
 96 |     """
 97 |     if page_size is None:
 98 |         page_size = get_page_size(endpoint)
 99 | 
100 |     url = '{}/{}'.format(api_base_url, endpoint)
101 |     parameters['page_number'] = page_number
102 |     parameters['page_size'] = page_size
103 | 
104 |     if cache_enabled:
105 |         response = _web_request_cached(url, parameters)
106 |     else:
107 |         response = _web_request(url, parameters)
108 | 
109 |     return json.loads(response)
110 | 
111 | 
112 | def _web_request(url, parameters):
113 |     """
114 |     Perform HTTP GET request and return response.
115 | 
116 |     Args:
117 |         url: Absolute URL
118 |         parameters: URL parameters
119 | 
120 |     Returns:
121 |         Response as a string
122 |     """
123 |     auth = (username, password)
124 | 
125 |     with sessions.Session() as session:
126 |         response = session.request('GET', url, params=parameters, auth=auth,
127 |                                    verify=True)
128 |     if not response.ok:
129 |         response.raise_for_status()
130 | 
131 |     return response.content.decode('utf-8')
132 | 
133 | 
134 | def _web_request_cached(url, parameters):
135 |     """
136 |     Return cached response if available and not too old, otherwise
137 |     perform HTTP GET request and cache and return response.
138 | 
139 |     Args:
140 |         url: Absolute URL
141 |         parameters: URL parameters
142 | 
143 |     Returns:
144 |         Response as a string
145 |     """
146 |     content_id = (url + json.dumps(parameters)).encode('utf-8')
147 |     content_key = hashlib.sha256(content_id).hexdigest()
148 |     cache_file_path = os.path.join(cache_directory, content_key + '.txt')
149 | 
150 |     if os.path.exists(cache_file_path):
151 |         age = time.time() - os.path.getctime(cache_file_path)
152 | 
153 |         if age <= cache_max_age:
154 |             with codecs.open(cache_file_path, 'r', 'utf-8') as cached_response:
155 |                 return cached_response.read()
156 | 
157 |     response = _web_request(url, parameters)
158 | 
159 |     if not os.path.exists(cache_directory):
160 |         os.makedirs(cache_directory)
161 | 
162 |     with codecs.open(cache_file_path, 'w', 'utf-8') as cached_response:
163 |         cached_response.write(response)
164 | 
165 |     return response
166 | 
167 | 
168 | def get_page_size(endpoint):
169 |     """
170 |     Get page size for a specific endpoint.
171 | 
172 |     Args:
173 |         endpoint: Intrinio endpoint, for example: companies
174 | 
175 |     Returns:
176 |         Page size as number of rows
177 |     """
178 |     return page_sizes.get(endpoint.lower(), default_page_size)
179 | 


--------------------------------------------------------------------------------
/intrinio/endpoints.py:
--------------------------------------------------------------------------------
  1 | import pandas as pd
  2 | import numpy as np
  3 | from intrinio.client import get
  4 | 
  5 | 
  6 | def companies(identifier=None, query=None):
  7 |     """
  8 |     Get companies with optional filtering using parameters.
  9 | 
 10 |     Args:
 11 |         identifier: Identifier for the legal entity or a security associated
 12 |             with the company: TICKER SYMBOL | FIGI | OTHER IDENTIFIER
 13 |         query: Search of company name or ticker symbol
 14 | 
 15 |     Returns:
 16 |         Dataset as a Pandas DataFrame
 17 |     """
 18 |     return get('companies',
 19 |                identifier=_upper_optional(identifier),
 20 |                query=query)
 21 | 
 22 | 
 23 | def securities(identifier=None, query=None, exch_symbol=None):
 24 |     """
 25 |     Get securities with optional filtering using parameters.
 26 | 
 27 |     Args:
 28 |         identifier: Identifier for the legal entity or a security associated
 29 |             with the company: TICKER SYMBOL | FIGI | OTHER IDENTIFIER
 30 |         query: Search of security name or ticker symbol
 31 |         exch_symbol: Exchange symbol
 32 | 
 33 |     Returns:
 34 |         Dataset as a Pandas DataFrame
 35 |     """
 36 |     return get('securities',
 37 |                identifier=_upper_optional(identifier),
 38 |                query=query,
 39 |                exch_symbol=_upper_optional(exch_symbol))
 40 | 
 41 | 
 42 | def indices(identifier=None, query=None, type=None):
 43 |     """
 44 |     Get indices with optional filtering using parameters.
 45 | 
 46 |     Args:
 47 |         identifier: Intrinio symbol associated with the index
 48 |         query: Search of index name or symbol
 49 |         type: Type of indices: stock_market | economic | sic
 50 | 
 51 |     Returns:
 52 |         Dataset as a Pandas DataFrame
 53 |     """
 54 |     return get('indices',
 55 |                identifier=_upper_optional(identifier),
 56 |                query=query,
 57 |                type=_lower_optional(type))
 58 | 
 59 | 
 60 | def prices(identifier, start_date=None, end_date=None, frequency='daily',
 61 |            sort_order='desc'):
 62 |     """
 63 |     Get historical stock market prices or indices.
 64 | 
 65 |     Args:
 66 |         identifier: Stock market symbol or index
 67 |         start_date: Start date of prices (default no filter)
 68 |         end_date: Last date (default today)
 69 |         frequency: Frequency of prices: daily (default) | weekly | monthly |
 70 |             quarterly | yearly
 71 |         sort_order: Order of prices: asc | desc (default)
 72 | 
 73 |     Returns:
 74 |         Dataset as a Pandas DataFrame
 75 |     """
 76 |     df = get('prices',
 77 |              identifier=identifier.upper(),
 78 |              start_date=start_date,
 79 |              end_date=end_date,
 80 |              frequency=frequency.lower(),
 81 |              sort_order=sort_order.lower())
 82 | 
 83 |     df.index = pd.DatetimeIndex(df.date)
 84 |     df.drop('date', axis=1, inplace=True)
 85 |     return df
 86 | 
 87 | 
 88 | def news(identifier):
 89 |     """
 90 |     Get news for a company.
 91 | 
 92 |     Args:
 93 |         identifier: stock market ticker symbol associated with the company's
 94 |             common stock. If the company is foreign, use the stock exchange
 95 |             code, followed by a colon, then the ticker.
 96 | 
 97 |     Returns:
 98 |         Dataset as a Pandas DataFrame
 99 |     """
100 |     return get('news', identifier=identifier.upper())
101 | 
102 | 
103 | def fundamentals(identifier, type='FY', statement='calculations'):
104 |     """
105 |     Get available periods with standardized fundamental data for a company.
106 | 
107 |     Args:
108 |         identifier: stock market ticker symbol associated with the company's
109 |             common stock. If the company is foreign, use the stock exchange
110 |             code, followed by a colon, then the ticker.
111 |         type: Period type: FY (default) | QTR | TTM | YTD
112 |         statement: Type of fundamental data: calculations (default) |
113 |             income_statement | balance_sheet | cash_flow_statement
114 | 
115 |     Returns:
116 |         Dataset as a Pandas DataFrame
117 |     """
118 |     return get('fundamentals/standardized',
119 |                identifier=identifier.upper(),
120 |                statement=statement.lower(),
121 |                type=type.upper())
122 | 
123 | 
124 | def financials(identifier, type='FY', statement='calculations'):
125 |     """
126 |     Get standardized fundamental data for a company.
127 | 
128 |     Args:
129 |         identifier: stock market ticker symbol associated with the company's
130 |             common stock. If the company is foreign, use the stock exchange
131 |             code, followed by a colon, then the ticker.
132 |         type: Period type: FY (default) | QTR | TTM | YTD
133 |         statement: Type of fundamental data: calculations (default) |
134 |             income_statement | balance_sheet | cash_flow_statement
135 | 
136 |     Returns:
137 |         Dataset as a Pandas DataFrame
138 |     """
139 |     identifier = identifier.upper()
140 |     type = type.upper()
141 |     statement = statement.lower()
142 | 
143 |     f = fundamentals(identifier, type, statement)
144 |     years_and_periods = zip(f.fiscal_year, f.fiscal_period)
145 |     r = None
146 | 
147 |     for fiscal_year, fiscal_period in years_and_periods:
148 |         period = financials_period(identifier, fiscal_year, fiscal_period,
149 |                                    statement)
150 | 
151 | 
152 |         if type == 'TTM' and fiscal_period == 'FY':
153 |             period.index = pd.MultiIndex.from_tuples([(fiscal_year, 'Q4TTM')],
154 |                                                      names=['year', 'period'])
155 |         if r is None:
156 |             r = period
157 |         else:
158 |             r = pd.concat([r, period], sort=False)
159 | 
160 |     r = r.sort_index()
161 |     return r
162 | 
163 | 
164 | def financials_period(identifier, fiscal_year, fiscal_period='FY',
165 |                       statement='calculations'):
166 |     """
167 |     Get standardized fundamental data for a single period for a company.
168 | 
169 |     Args:
170 |         fiscal_year: Year
171 |         fiscal_period: FY (default) | Q1 | Q2 | Q3 | Q4 | Q1TTM | Q2TTM | Q3TTM
172 |             | Q2YTD | Q3YTD
173 |         identifier: stock market ticker symbol associated with the company's
174 |             common stock. If the company is foreign, use the stock exchange
175 |             code, followed by a colon, then the ticker.
176 |         statement: Type of fundamental data: calculations (default) |
177 |             income_statement | balance_sheet | cash_flow_statement
178 | 
179 |     Returns:
180 |         Dataset as a Pandas DataFrame
181 |     """
182 |     identifier = identifier.upper()
183 |     fiscal_period = fiscal_period.upper()
184 |     statement = statement.lower()
185 | 
186 |     if isinstance(fiscal_year, np.generic):
187 |         fiscal_year = np.asscalar(fiscal_year)
188 | 
189 |     if fiscal_period == 'FY':
190 |         index = [fiscal_year]
191 |     else:
192 |         index = pd.MultiIndex.from_tuples([(fiscal_year, fiscal_period)],
193 |                                           names=['year', 'period'])
194 | 
195 |     r = get('financials/standardized',
196 |             identifier=identifier,
197 |             statement=statement,
198 |             fiscal_year=fiscal_year,
199 |             fiscal_period=fiscal_period)
200 | 
201 |     r = pd.DataFrame(dict(zip(r.tag, r.value)), columns=r.tag, index=index)
202 |     r.columns.name = None
203 |     r = r.apply(pd.to_numeric, errors='coerce')
204 | 
205 |     if fiscal_period == 'FY':
206 |         r.index.name = 'year'
207 | 
208 |     # Remove duplicate columns from Intrinio
209 |     r = r.loc[:, ~r.columns.duplicated()]
210 | 
211 |     return r
212 | 
213 | 
214 | def screener(conditions, order_column=None, order_direction=None,
215 |              primary_only=None, logic=None):
216 |     """
217 |     Find securities that meet a list of conditions.
218 | 
219 |     Args:
220 |         conditions: Comma-separated list of conditions. Each condition
221 |             consists of three or four elements separated by tildes (~):
222 |             Data_tag~Operator~Value~Label(Optional)
223 |         order_column: A data tag by which to order the results
224 |         order_direction: Order of the results: asc (default) | desc
225 |         primary_only: Return only primary securities (excluding special
226 |             securities such as preferred shares)
227 |         logic: How the conditions are applied using AND by default
228 | 
229 |     Returns:
230 |         List of tickers that meet the conditions as a Pandas DataFrame
231 |     """
232 |     return get('securities/search',
233 |                conditions=conditions,
234 |                order_column=order_column,
235 |                order_direction=order_direction,
236 |                primary_only=primary_only,
237 |                logic=logic)
238 | 
239 | 
240 | def _lower_optional(x):
241 |     if x is not None:
242 |         return x.lower()
243 |     else:
244 |         return None
245 | 
246 | 
247 | def _upper_optional(x):
248 |     if x is not None:
249 |         return x.upper()
250 |     else:
251 |         return None
252 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # intrinio
  2 | 
  3 | Unofficial Intrinio API V1 client for Python.
  4 | It gives easy access to financial data.
  5 | 
  6 | **OBS: This package targets Intrinio API V1. Now that they have released an
  7 | official Python package and at the same time released a new incompatible API V2
  8 | I recommend using the their official Python package available
  9 | here: https://github.com/intrinio/python-sdk**
 10 | 
 11 | ## Setup
 12 | 
 13 | Install this package by using the pip tool:
 14 | 
 15 | ```bash
 16 | pip install intrinio
 17 | ```
 18 | 
 19 | Before retrieving data using the package the API username and password has to be
 20 | configured, either by setting the username and password attributes of the
 21 | intrinio package:
 22 | 
 23 | ```python
 24 | import intrinio
 25 | intrinio.client.username = 'USERNAME_FROM_INTRINIO'
 26 | intrinio.client.password = 'PASSWORD_FROM_INTRINIO'
 27 | ```
 28 | 
 29 | Or by setting the system environment variables:
 30 | 
 31 | * INTRINIO_USERNAME
 32 | * INTRINIO_PASSWORD
 33 | 
 34 | ## Quick start
 35 | 
 36 | Install the intrinio package, import it and set username and password as above first.
 37 | 
 38 | Get prices starting at 2016-01-01 for Apple:
 39 | 
 40 | ```python
 41 | intrinio.prices('AAPL', start_date='2016-01-01')
 42 | ```
 43 | 
 44 | Get yearly fundamentals including PE ratio, net debt, total capital and
 45 | over 100 other variables for Apple:
 46 | 
 47 | ```python
 48 | intrinio.financials('AAPL')
 49 | ```
 50 | 
 51 | Get company information about Google:
 52 | 
 53 | ```python
 54 | intrinio.companies('GOOG')
 55 | ```
 56 | 
 57 | Get company information about Google using the low level **get** function:
 58 | 
 59 | ```python
 60 | intrinio.get('companies', identifier='GOOG')
 61 | ```
 62 | 
 63 | Get cik, lei, name and ticker of companies with "Bank" in their company name:
 64 | 
 65 | ```python
 66 | intrinio.companies(query='Bank')
 67 | ```
 68 | 
 69 | Screen stocks with PE higher than 10:
 70 | 
 71 | ```python
 72 | intrinio.screener('pricetoearnings~gt~10')
 73 | ```
 74 | 
 75 | ## Usage
 76 | 
 77 | There are a high- and low level functions used to access the Intrinio API.
 78 | 
 79 | The high level functions are mostly simple wrappers of the **get** function
 80 | that retrieves all data with optional parameters to filter the data. They
 81 | might also do some data conversion like for example the prices endpoint
 82 | where the date column is used as the index for the Pandas DataFrame.
 83 | 
 84 | For more information about available endpoints and their parameters,
 85 | see Intrinio API documentation at: [Intrinio Docs](http://docs.intrinio.com/)
 86 | 
 87 | ### Low level functions
 88 | 
 89 | * get(endpoint, **parameters):
 90 | 
 91 |     Get complete dataset from an endpoint using optional query parameters.
 92 | 
 93 |     Args:
 94 | 
 95 |         endpoint: Intrinio endpoint, for example: companies
 96 |         parameters: Optional query parameters
 97 | 
 98 |     Returns:
 99 |         Dataset as a Pandas DataFrame
100 | 
101 | * get_page(endpoint, page_number=1, page_size=None, **parameters):
102 | 
103 |     Get a dataset page from an endpoint using optional query parameters.
104 | 
105 |     Args:
106 | 
107 |         endpoint: Intrinio endpoint, for example: companies
108 |         page_number: Optional page number where 1 is first page (default 1)
109 |         page_size: Optional page size (default max page size for the endpoint)
110 |         parameters: Optional query parameters
111 | 
112 |     Returns:
113 |         Dataset page as a Pandas DataFrame with an additional total_pages
114 |         attribute
115 | 
116 | ### High level functions
117 | 
118 | * companies(identifier=None, query=None):
119 | 
120 |     Get companies with optional filtering using parameters.
121 | 
122 |     Args:
123 | 
124 |         identifier: Identifier for the legal entity or a security associated
125 |             with the company: TICKER SYMBOL | FIGI | OTHER IDENTIFIER
126 |         query: Search of company name or ticker symbol
127 | 
128 |     Returns:
129 |         Dataset as a Pandas DataFrame
130 | 
131 | * securities(identifier=None, query=None, exch_symbol=None):
132 | 
133 |     Get securities with optional filtering using parameters.
134 | 
135 |     Args:
136 | 
137 |         identifier: Identifier for the legal entity or a security associated
138 |             with the company: TICKER SYMBOL | FIGI | OTHER IDENTIFIER
139 |         query: Search of security name or ticker symbol
140 |         exch_symbol: Exchange symbol
141 | 
142 |     Returns:
143 |         Dataset as a Pandas DataFrame
144 | 
145 | * indices(identifier=None, query=None, type=None):
146 | 
147 |     Get indices with optional filtering using parameters.
148 | 
149 |     Args:
150 | 
151 |         identifier: Intrinio symbol associated with the index
152 |         query: Search of index name or symbol
153 |         type: Type of indices: stock_market | economic | sic
154 | 
155 |     Returns:
156 |         Dataset as a Pandas DataFrame
157 | 
158 | * prices(identifier, start_date=None, end_date=None, frequency='daily',
159 |            sort_order='desc'):
160 | 
161 |     Get historical stock market prices or indices.
162 | 
163 |     Args:
164 | 
165 |         identifier: Stock market symbol or index
166 |         start_date: Start date of prices (default no filter)
167 |         end_date: Last date (default today)
168 |         frequency: Frequency of prices: daily (default) | weekly | monthly |
169 |             quarterly | yearly
170 |         sort_order: Order of prices: asc | desc (default)
171 | 
172 |     Returns:
173 |         Dataset as a Pandas DataFrame
174 | 
175 | * news(identifier):
176 | 
177 |     Get news for a company.
178 | 
179 |     Args:
180 | 
181 |         identifier: stock market ticker symbol associated with the company's
182 |             common stock. If the company is foreign, use the stock exchange
183 |             code, followed by a colon, then the ticker.
184 | 
185 |     Returns:
186 |         Dataset as a Pandas DataFrame
187 | 
188 | * financials(identifier, type='FY', statement='calculations'):
189 | 
190 |     Get standardized fundamental data for a company.
191 | 
192 |     Args:
193 | 
194 |         identifier: stock market ticker symbol associated with the company's
195 |             common stock. If the company is foreign, use the stock exchange
196 |             code, followed by a colon, then the ticker.
197 |         type: Period type: FY (default) | QTR | TTM | YTD
198 |         statement: Type of fundamental data: calculations (default) |
199 |             income_statement | balance_sheet | cash_flow_statement
200 | 
201 |     Returns:
202 |         Dataset as a Pandas DataFrame
203 | 
204 | * financials_period(identifier, fiscal_year, fiscal_period='FY',
205 |                       statement='calculations'):
206 | 
207 |     Get standardized fundamental data for a single period for a company.
208 | 
209 |     Args:
210 | 
211 |         fiscal_year: Year
212 |         fiscal_period: FY (default) | Q1 | Q2 | Q3 | Q4 | Q1TTM | Q2TTM | Q3TTM
213 |             | Q2YTD | Q3YTD
214 |         identifier: stock market ticker symbol associated with the company's
215 |             common stock. If the company is foreign, use the stock exchange
216 |             code, followed by a colon, then the ticker.
217 |         statement: Type of fundamental data: calculations (default) |
218 |             income_statement | balance_sheet | cash_flow_statement
219 | 
220 |     Returns:
221 |         Dataset as a Pandas DataFrame
222 | 
223 | * fundamentals(identifier, type='FY', statement='calculations'):
224 | 
225 |     Get available periods with standardized fundamental data for a company.
226 | 
227 |     Args:
228 | 
229 |         identifier: stock market ticker symbol associated with the company's
230 |             common stock. If the company is foreign, use the stock exchange
231 |             code, followed by a colon, then the ticker.
232 |         type: Period type: FY (default) | QTR | TTM | YTD
233 |         statement: Type of fundamental data: calculations (default) |
234 |             income_statement | balance_sheet | cash_flow_statement
235 | 
236 |     Returns:
237 |         Dataset as a Pandas DataFrame
238 | 
239 | * screener(conditions, order_column=None, order_direction=None,
240 |              primary_only=None, logic=None):
241 | 
242 |     Find securities that meet a list of conditions.
243 | 
244 |     Args:
245 | 
246 |         conditions: Comma-separated list of conditions. Each condition
247 |             consists of three or four elements separated by tildes (~):
248 |             Data_tag~Operator~Value~Label(Optional)
249 |         order_column: A data tag by which to order the results
250 |         order_direction: Order of the results: asc (default) | desc
251 |         primary_only: Return only primary securities (excluding special
252 |             securities such as preferred shares)
253 |         logic: How the conditions are applied using AND by default
254 | 
255 |     Returns:
256 |         List of tickers that meet the conditions as a Pandas DataFrame
257 | 
258 | ## Tests
259 | 
260 | The tests will cache API requests in ~/.cache/intrinio to make the tests go
261 | faster and avoid excessive API traffic. It is not recommended to use caching
262 | for non-testing purposes, it should only be used for tests.
263 | 
264 | Run the tests using pytest in the root directory of the project:
265 | 
266 | ```bash
267 | py.test
268 | ```
269 | 
270 | Or run the runtests script to also generate a coverage report
271 | (saved to tmp/).
272 | 
273 | ```bash
274 | bin/runtests
275 | ```
276 | 
277 | ## Version history
278 | 
279 | * See CHANGELOG.md
280 | 
281 | ## License
282 | 
283 | * MIT License
284 | 


--------------------------------------------------------------------------------