RavenPack API - Python client
=============================
A Python library to consume the
`RavenPack <https://www.ravenpack.com>`__ API.
`API documentation. <https://www.ravenpack.com/support/>`__
Installation
------------
::
pip install ravenpackapi
About
-----
The Python client helps managing the API calls to the RavenPack dataset
server in a Pythonic way, here are some examples of usage, you can find
more in the tests.
Usage
-----
In order to be able to use the RavenPack API you will need an API KEY.
If you don't already have one please contact your `customer
support <mailto:sales@ravenpack.com>`__ representative.
To begin using the API you will need to instantiate an API object that
will deal with the API calls.
Using your RavenPack API KEY, you can either set the ``RP_API_KEY``
environment variable or set it in your code:
.. code:: python
from ravenpackapi import RPApi
api = RPApi(api_key="YOUR_API_KEY")
Creating a new dataset
~~~~~~~~~~~~~~~~~~~~~~
To create a dataset you can call the ``create_dataset`` method of the
API with a Dataset instance.
.. code:: python
from ravenpackapi import Dataset
ds = api.create_dataset(
Dataset(
name="New Dataset",
filters={
"relevance": {
"$gte": 90
}
},
)
)
print("Dataset created", ds)
Getting data from the datasets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the API wrapper, there are several models that maybe used for
interacting with data.
Here is how you may get a dataset definition for a pre-existing dataset
.. code:: python
# Get the dataset description from the server, here we use 'us30'
# one of RavenPack public datasets with the top30 companies in the US
ds = api.get_dataset(dataset_id='us30')
Downloads: json
^^^^^^^^^^^^^^^
The json endpoint is useful for asking data synchronously, optimized for
small requests, if you need to download big data chunks you may want to
use the asynchronous datafile endpoint instead.
.. code:: python
data = ds.json(
start_date='2018-01-05 18:00:00',
end_date='2018-01-05 18:01:00',
)
for record in data:
print(record)
Json queries are limited to
- granular datasets: 10,000 records
- indicator datasets: 500 entities, timerange 1 year, lookback window 1
year
Downloads: datafile
^^^^^^^^^^^^^^^^^^^
For bigger requests the datafile endpoint can be used to prepare a
datafile asynchronously on the RavenPack server for later retrieval.
Requesting a datafile, will give you back a job object, that will take
some time to complete.
.. code:: python
job = ds.request_datafile(
start_date='2018-01-05 18:00:00',
end_date='2018-01-05 18:01:00',
)
with open('output.csv') as fp:
job.save_to_file(filename=fp.name)
Streaming real-time data
~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to subscribe to a real-time stream for a dataset.
Once you create a streaming connection to the real-time feed with your
dataset, you will receive analytics records as soon as they are
published.
It is suggested to handle possible disconnection with a retry policy.
You can find a `real-time streaming example
here <ravenpackapi/examples/get_realtime_news.py>`__.
The Result object handles the conversion of various fields into the
appropriate type, i.e. ``record.timestamp_utc`` will be converted to
``datetime``
Entity mapping
~~~~~~~~~~~~~~
The entity mapping endpoint allow you to find the RP\_ENTITY\_ID mapped
to your universe of entities.
.. code:: python
universe = [
"RavenPack",
{'ticker': 'AAPL'},
{ # 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 Ltd.",
"Apple Inc.",
"Amazon.com Inc."
]
Entity reference
~~~~~~~~~~~~~~~~
The entity reference endpoint give you all the available information for
an Entity given the RP\_ENTITY\_ID
.. code:: python
ALPHABET_RP_ENTITY_ID = '4A6F00'
references = api.get_entity_reference(ALPHABET_RP_ENTITY_ID)
# show all the names over history
for name in references.names:
print(name.value, name.start, name.end)
# print all the ticket valid today
for ticker in references.tickers:
if ticker.is_valid():
print(ticker)
Training Datasets
~~~~~~~~~~~~~~~~~
Analyse your own content using RavenPack’s proprietary NLP technology.
The API for analyzing your internal content is still in beta and may
change in the future. You can request an early access and `see an
example of usage here <ravenpackapi/examples/text_extraction.py>`__.
Accessing the low-level requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
RavenPack API wrapper is using the `requests
library <https://2.python-requests.org>`__ to do HTTPS requests, you can
set common requests parameters to all the outbound calls by setting the
``common_request_params`` attribute.
For example, to disable HTTPS certificate verification and to setup your
internal proxy:
.. code:: python
api = RPApi()
api.common_request_params.update(
dict(
proxies={'https': 'http://your_internal_proxy:9999'},
verify=False,
)
)
# use the api to do requests
PS. For setting your internal proxies, requests will honor the
HTTPS\_PROXY environment variable.
Raw data
{
"_id": null,
"home_page": "https://github.com/RavenPack/python-api",
"name": "ravenpackapi",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python analytics api rest news data",
"author": "RavenPack",
"author_email": "dataservices@ravenpack.com",
"download_url": "https://files.pythonhosted.org/packages/fc/09/d8c2026a77ff4adfc5c4c1807aa671cb173345c4858e6589613d474608ae/ravenpackapi-1.1.6.tar.gz",
"platform": null,
"description": "RavenPack API - Python client\n=============================\n\nA Python library to consume the\n`RavenPack <https://www.ravenpack.com>`__ API.\n\n`API documentation. <https://www.ravenpack.com/support/>`__\n\nInstallation\n------------\n\n::\n\n pip install ravenpackapi\n\nAbout\n-----\n\nThe Python client helps managing the API calls to the RavenPack dataset\nserver in a Pythonic way, here are some examples of usage, you can find\nmore in the tests.\n\nUsage\n-----\n\nIn order to be able to use the RavenPack API you will need an API KEY.\nIf you don't already have one please contact your `customer\nsupport <mailto:sales@ravenpack.com>`__ representative.\n\nTo begin using the API you will need to instantiate an API object that\nwill deal with the API calls.\n\nUsing your RavenPack API KEY, you can either set the ``RP_API_KEY``\nenvironment variable or set it in your code:\n\n.. code:: python\n\n from ravenpackapi import RPApi\n\n api = RPApi(api_key=\"YOUR_API_KEY\")\n\nCreating a new dataset\n~~~~~~~~~~~~~~~~~~~~~~\n\nTo create a dataset you can call the ``create_dataset`` method of the\nAPI with a Dataset instance.\n\n.. code:: python\n\n from ravenpackapi import Dataset\n\n ds = api.create_dataset(\n Dataset(\n name=\"New Dataset\",\n filters={\n \"relevance\": {\n \"$gte\": 90\n }\n },\n )\n )\n print(\"Dataset created\", ds)\n\nGetting data from the datasets\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIn the API wrapper, there are several models that maybe used for\ninteracting with data.\n\nHere is how you may get a dataset definition for a pre-existing dataset\n\n.. code:: python\n\n # Get the dataset description from the server, here we use 'us30'\n # one of RavenPack public datasets with the top30 companies in the US \n\n ds = api.get_dataset(dataset_id='us30')\n\nDownloads: json\n^^^^^^^^^^^^^^^\n\nThe json endpoint is useful for asking data synchronously, optimized for\nsmall requests, if you need to download big data chunks you may want to\nuse the asynchronous datafile endpoint instead.\n\n.. code:: python\n\n data = ds.json(\n start_date='2018-01-05 18:00:00',\n end_date='2018-01-05 18:01:00',\n )\n\n for record in data:\n print(record)\n\nJson queries are limited to\n\n- granular datasets: 10,000 records\n- indicator datasets: 500 entities, timerange 1 year, lookback window 1\n year\n\nDownloads: datafile\n^^^^^^^^^^^^^^^^^^^\n\nFor bigger requests the datafile endpoint can be used to prepare a\ndatafile asynchronously on the RavenPack server for later retrieval.\n\nRequesting a datafile, will give you back a job object, that will take\nsome time to complete.\n\n.. code:: python\n\n job = ds.request_datafile(\n start_date='2018-01-05 18:00:00',\n end_date='2018-01-05 18:01:00',\n )\n\n with open('output.csv') as fp:\n job.save_to_file(filename=fp.name)\n\nStreaming real-time data\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nIt is possible to subscribe to a real-time stream for a dataset.\n\nOnce you create a streaming connection to the real-time feed with your\ndataset, you will receive analytics records as soon as they are\npublished.\n\nIt is suggested to handle possible disconnection with a retry policy.\nYou can find a `real-time streaming example\nhere <ravenpackapi/examples/get_realtime_news.py>`__.\n\nThe Result object handles the conversion of various fields into the\nappropriate type, i.e. ``record.timestamp_utc`` will be converted to\n``datetime``\n\nEntity mapping\n~~~~~~~~~~~~~~\n\nThe entity mapping endpoint allow you to find the RP\\_ENTITY\\_ID mapped\nto your universe of entities.\n\n.. code:: python\n\n universe = [\n \"RavenPack\",\n {'ticker': 'AAPL'},\n { # Amazon, specifying various fields\n \"client_id\": \"12345-A\",\n \"date\": \"2017-01-01\",\n \"name\": \"Amazon Inc.\",\n \"entity_type\": \"COMP\",\n \"isin\": \"US0231351067\",\n \"cusip\": \"023135106\",\n \"sedol\": \"B58WM62\",\n \"listing\": \"XNAS:AMZN\"\n },\n\n ]\n mapping = api.get_entity_mapping(universe)\n\n # in this case we match everything\n assert len(mapping.matched) == len(universe)\n assert [m.name for m in mapping.matched] == [\n \"RavenPack Ltd.\",\n \"Apple Inc.\",\n \"Amazon.com Inc.\"\n ]\n\nEntity reference\n~~~~~~~~~~~~~~~~\n\nThe entity reference endpoint give you all the available information for\nan Entity given the RP\\_ENTITY\\_ID\n\n.. code:: python\n\n ALPHABET_RP_ENTITY_ID = '4A6F00'\n\n references = api.get_entity_reference(ALPHABET_RP_ENTITY_ID)\n\n # show all the names over history\n for name in references.names:\n print(name.value, name.start, name.end)\n\n # print all the ticket valid today\n for ticker in references.tickers:\n if ticker.is_valid():\n print(ticker)\n\nTraining Datasets\n~~~~~~~~~~~~~~~~~\n\nAnalyse your own content using RavenPack\u2019s proprietary NLP technology.\n\nThe API for analyzing your internal content is still in beta and may\nchange in the future. You can request an early access and `see an\nexample of usage here <ravenpackapi/examples/text_extraction.py>`__.\n\nAccessing the low-level requests\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nRavenPack API wrapper is using the `requests\nlibrary <https://2.python-requests.org>`__ to do HTTPS requests, you can\nset common requests parameters to all the outbound calls by setting the\n``common_request_params`` attribute.\n\nFor example, to disable HTTPS certificate verification and to setup your\ninternal proxy:\n\n.. code:: python\n\n api = RPApi()\n api.common_request_params.update(\n dict(\n proxies={'https': 'http://your_internal_proxy:9999'},\n verify=False,\n )\n )\n\n # use the api to do requests\n\nPS. For setting your internal proxies, requests will honor the\nHTTPS\\_PROXY environment variable.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "RavenPack API - Python client",
"version": "1.1.6",
"project_urls": {
"Homepage": "https://github.com/RavenPack/python-api"
},
"split_keywords": [
"python",
"analytics",
"api",
"rest",
"news",
"data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc09d8c2026a77ff4adfc5c4c1807aa671cb173345c4858e6589613d474608ae",
"md5": "2efa3b7cb2597245902ba74961ffa0b1",
"sha256": "c279d34eb4e1f791919c291e798aaa3b5a68c55d2aa42b12c8d5a391813211d3"
},
"downloads": -1,
"filename": "ravenpackapi-1.1.6.tar.gz",
"has_sig": false,
"md5_digest": "2efa3b7cb2597245902ba74961ffa0b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 47434,
"upload_time": "2024-07-10T12:11:25",
"upload_time_iso_8601": "2024-07-10T12:11:25.591249Z",
"url": "https://files.pythonhosted.org/packages/fc/09/d8c2026a77ff4adfc5c4c1807aa671cb173345c4858e6589613d474608ae/ravenpackapi-1.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-10 12:11:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RavenPack",
"github_project": "python-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "six",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "tenacity",
"specs": []
}
],
"tox": true,
"lcname": "ravenpackapi"
}
JSON
