a Python package for calling the OpenCorporates API
opyncorporates is a Python wrapper for the OpenCorporates API.
It allows a user to create an
Engine object that interacts with the API
through two simple methods:
fetch methods use signatures that mimic the request
arguments and variables required in the GET requests through the
OpenCorporates API, while eliminating some of the cruft.
For example, a request to search for a company by name through the OpenCorporates API might look something like this:
Submitting 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)
fetch methods return
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
This section will show you how to get up and running with the
opyncorporates package. Additional information can be found in the
To get started, you can install the package using
$ pip install opyncorporates
Once the package is installed, you can use it to create an
Engine object for submitting requests and retrieving data through the
OpenCorporates API. When creating an
Engine object, 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 the OpenCorporates 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 an
Engine object, you
can start making calls to the OpenCorporates API.
In general, each of your API calls will perform only one of two actions. It
- search for potential matches to a specified string value, or
- fetch a specific object by its unique identifier
There is a third action available when seeking information about a particular object using an imprecise identifier. This third action allows you to match to 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 generic request to 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.
Engine object implements searches through the
search method, which
>>> 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 >] >>> search.response # the most recent response for this request <Response > >>> search.total_pages 26 >>> search.per_page 30 >>> search.total_count 764
You can then use the properties of this
SearchRequest object 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 the OpenCorporates API:
>>> first_page = search.get_page(1) >>> print(type(first_page)) <class 'list'> >>> print(len(first_page)) 30 >>> print(type(first_page)) <class 'dict'>
fetch method 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 the OpenCorporates API
by 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 >] >>> fetch.response # the most recent response for this request <Response > >>> 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 the
match method implements the third available action. It allows a user to
match a specified string value to a single item in the OpenCorporates
database. As of version 0.4, the OpenCorporates API exposes this action to
match jurisdictions only:
>>> from opyncorporates import create_engine >>> engine = create_engine() >>> match = engine.match('jurisdictions', q='U.K.')
request method 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
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size opyncorporates-0.1.0-py3-none-any.whl (9.6 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size opyncorporates-0.1-py3-none-any.whl (9.6 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size opyncorporates-0.1.tar.gz (8.8 kB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for opyncorporates-0.1.0-py3-none-any.whl
Hashes for opyncorporates-0.1-py3-none-any.whl