Package: opyncorporates
Overviewopyncorporatesis a Python wrapper for theOpenCorporates API.
It allows a user to create anEngineobject that interacts with the API
through two simple methods:searchandfetch.Thesearchandfetchmethods use signatures that mimic the request
arguments and variables required in the GET requests through theOpenCorporates API,
while eliminating some of the cruft.For example, a request to search for a company by name through theOpenCorporates APImight look something like this:GET https://api.opencorporates.com/v0.4/companies/search?q=bar&per_page=100Submitting the same request through the search method of of an opyncorporates
Engine object, on the other hand, would look like this:>>> from opyncorporates import create_engine
>>> engine = create_engine(api_version='0.4')
>>> search = engine.search('companies', q='bar', per_page=100)Both thesearchandfetchmethods returnopyncorporates.Requestobjects,
which allow the user (1) to explore information related to a request and (2) to
obtain results more easily than it would be to craft a series of successive API
calls.Getting StartedThis section will show you how to get up and running with theopyncorporatespackage. Additional information can be found in the
documentationhere.To get started, you can install the package usingpip:$ pip install opyncorporatesOnce the package is installed, you can use it to create anEngineobject for submitting requests and retrieving data through the
OpenCorporates API. When creating anEngineobject, you have the option of
specifying an API version and an API token:>>> from opyncorporates import create_engine
>>> engine = create_engine(api_version='0.4',
...                        api_token='<api-token>')
>>> engine.api_version
'0.4'The API version and API token will be used when building the urls required to
submit requests to theOpenCorporates API.
As of now, the package's default API version is 0.4, and it is the only
version supported. If you are planning to query the API on a regular basis, I
highly recommend purchasing an API token to increase your call limits.Once you have created anEngineobject, you
can start making calls to theOpenCorporates API.
In general, each of your API calls will perform only one of two actions. It
will either:searchfor potential matches to a specified string value, orfetcha specific object by its unique identifierThere is a third action available when seeking information about a particular
object using an imprecise identifier. This third action allows you tomatchto an object by providing a string value for that object's name.Finally, if none of these actions suit your purposes, you can make a genericrequestto the API and parse the response yourself.The call signatures for the methods associated with each action mimic HTTPS
calls to the API. Http request args are
submitted to the method as positional arguments, while request variables are
submitted as keyword arguments.Further explanation of the search, fetch, match, and request actions can be
found below.SearchYourEngineobject implements searches through thesearchmethod, which
returns aSearchRequestobject:>>> from opyncorporates import create_engine
>>> engine = create_engine(api_version='0.4')
>>> search = engine.search('companies', 'search', q='Google')
>>> search.url
'https://api.opencorporates.com/v0.4/companies/search?q=google'
>>> search.responses # a history of responses for the object
[<Response [200]>]
>>> search.response # the most recent response for this request
<Response [200]>
>>> search.total_pages
26
>>> search.per_page
30
>>> search.total_count
764You can then use the properties of thisSearchRequestobject to return as
much or as little information from the OpenCorporates database as you need.
For example, if you want to retrieve only the first page of search results
from theOpenCorporates API:>>> first_page = search.get_page(1)
>>> print(type(first_page))
<class 'list'>
>>> print(len(first_page))
30
>>> print(type(first_page[0]))
<class 'dict'>FetchThefetchmethod implements the second available action. This method allows
a user to retrieve a specific item from the OpenCorporates API by providing
the item's type and unique identifier. For example, a user can retrieve a
specific company from theOpenCorporates APIby providing its item type (i.e., 'company' or 'companies') and its unique
identifier, which is the company's two-character country code plus its
company number unique to that jurisdiction:>>> from opyncorporates import create_engine
>>> engine = create_engine(api_version='0.4')
>>> fetch = engine.fetch('companies', 'gb', '00102498')
>>> fetch.responses # a history of responses for the object
[<Response [200]>]
>>> fetch.response # the most recent response for this request
<Response [200]>
>>> fetch.results['name']
'BP P.L.C.'
>>> fetch.results['incorporation_date']
'1909-04-14'If the fetch action is successful, the item is stored as a dict in theFetchRequestobject'sresultsattribute.MatchThematchmethod implements the third available action. It allows a user to
match a specified string value to a single item in theOpenCorporatesdatabase. As of version 0.4, theOpenCorporates APIexposes this action to
match jurisdictions only:>>> from opyncorporates import create_engine
>>> engine = create_engine()
>>> match = engine.match('jurisdictions', q='U.K.')RequestTherequestmethod implements a generic request action. It allows a user to
submit a request by supplying either (1) a string for the request args
and/or vars or (2) the request arguments and variables as positional and
keyword parameters. The engine will build a clean url for your request.For example, the same request for a search of company records can be written
in any of the following ways:>>> from opyncorporates import create_engine
>>> engine = create_engine()
>>> r1 = engine.request('companies/gb/00102498/search?q=google')
>>> r2 = engine.request('/companies/gb/00102498/search',
...                    q='Google')
>>> r3 = engine.request('companies', 'gb', '00102498', 'search'
...                    q='google')
>>> r1.url == r2.url == r3.url # confirm all urls are the same
True