api.py

The api.py submodule provides classes to build request objects that interface with the OpenCorporates API and return responses in Python atomic data types.

class opyncorporates.api.FetchRequest(api_version, object_type, *args, **kwargs)[source]

Get an item from the opencorporates API by unique identifier.

In most cases, a unique identifying number is provided after the object type. When selecting companies, however, the company’s two-character country code must be supplied, too.

See https://api.opencorporates.com/documentation/API-Reference for additional information on available arguments and keyword arguments.

officer = FetchRequest(‘v0.4’, ‘officers’, ‘123456’) company = FetchRequest(‘v0.4’, ‘companies’, ‘gb’, ‘00102498’)

api_version: str
The API version used for the request
object_type: str
The type of object to search for.
object_type: str
The requested object’s type.
results: dict
The requested item.
class opyncorporates.api.MatchRequest(cls, api_version, object_type, *args, **kwargs)[source]

Submits a match request to the opencorporates API.

The MatchRequest class is a subclass of the Request class. Like the Request class, the Search class is intended to mimic the opencorporates REST API syntax. Request args (i.e. arguments separated by ‘/’ characters following the base url) are provided as positional arguments, and request vars (i.e., key-value pairs following the ‘?’ character in the url and separated by ‘&’ characters) are provided as keyword arguments.

See https://api.opencorporates.com/documentation/API-Reference for additional information on available arguments and keyword arguments.

api_version: str
The API version used for the request
object_type: str
The type of object to search for.
q: str (optional)
The term that you are searching for
object_type: str
The type of object to search for.
search_term: str
The original term provided for the match request.
q: str
The match term transformed for use in the request url.
results: dict
The results of the match request.
class opyncorporates.api.Request(*args, **kwargs)[source]

An object for consuming the opencorporates API.

A user can instantiate a Request object in any one of the following three ways:

  • provide the complete request url as the first and only argument
  • provide the route url (i.e., the portion of the url following https://api.opencorporates.com) as the first and only argument
  • provide the request args as positional arguments and key-value pairs as keyword arguments

The last way is intended to mimic the opencorporates REST API syntax. Request args (i.e. arguments separated by ‘/’ characters following the base url) are provided as positional arguments, and request vars (i.e., key-value pairs following the ‘?’ character in the url and separated by ‘&’ characters) are provided as keyword arguments.

https://api.opencorporates.com/v0.4/companies/search?q=google –>
Request(‘https://api.opencorporates.com/v0.4/companies/search?q=google’) Request(‘/v0.4/companies/search?q=google’) Request(‘v0.4’, ‘companies’, ‘search’, q=’Google’)

See https://api.opencorporates.com/documentation/API-Reference for additional information on available arguments and keyword arguments.

_request_args:
The list of args used in the request.
_request_vars:
The list of key-value variables used in the request.
api_version: str
The API version used for the request.
api_token: str
The API token used for the request.
object_type: str
The type of object associated with the request.
url: str
The url for the request.
responses: list
A list of all responses objects returned by the Request object.
get_response()[source]

Submits the request to the opencorporates API.

When called, this method submits the request to the opencorporates API and appends it to the responses attribute.

response: obj
A requests.Models.Response object with a requested_at attribute.
response

Returns the most current response for the request.

response: obj
A requests.Models.Response object with a requested_at attribute.
class opyncorporates.api.SearchRequest(api_version, object_type, *args, **kwargs)[source]

Submits a search request to the opencorporates API.

The SearchRequest class is a subclass of the Request class. Like the Request class, the Search class is intended to mimic the opencorporates REST API syntax. Request args (i.e. arguments separated by ‘/’ characters following the base url) are provided as positional arguments, and request vars (i.e., key-value pairs following the ‘?’ character in the url and separated by ‘&’ characters) are provided as keyword arguments.

Search results are provided in a paginated format. Each page of the search results is obtained through a separate request to the opencorporates API with page=X supplied as a request variable.

See https://api.opencorporates.com/documentation/API-Reference for additional information on available arguments and keyword arguments.

api_version: str
The API version used for the request
object_type: str
The type of object to search for.
q: str (optional)
The term that you are searching for

In addition to the attributes exposed by the Request class:

object_type: str
The type of object to search for.
search_term: str
The original term provided for the search
q: str
The search term transformed for use in the request url
per_page: int
The number of search results per page
total_pages: int
The total number of pages of search results
total_count: int
The total number of search results
page_urls: list
A list of all request urls for obtaining the search results
get_page(page)[source]

Calls the opencorporates API and returns a page of results.

page : int
the page of search results to return.
list
A list of dict objects
results

Yields all search results.

item: dict
A dictionary representing a search result item.