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.