GovQA-Py Documentation

A Python client for interacting with GovQA, a public records request management platform owned by Granicus.

Setup

Get the library and its dependencies using pip:

pip install govqa

Usage

from govqa import GovQA, IncorrectCaptcha

DOMAIN = ""
EMAIL_ADDRESS = ""
PASSWORD = ""

# Instantiate an instance of the GovQA client
client = GovQA(DOMAIN, retry_attempts=3)

# get a new account form
form = client.new_account_form()

# If there are captcha's write to disk. alternatively you could try to solve them
if form.captcha:
    with open("out.jpg", "wb") as f:
        f.write(form.captcha["jpeg"].getbuffer())

success = False
captcha = None
while not success:
    if form.captcha:
        captcha = input("Captcha please: ")
    try:
        success = form.submit(
            {
                "email_address": EMAIL_ADDRESS,
                "password": PASSWORD,
                "phone": "5299299999",
                "captcha": captcha,
            }
        )
    except IncorrectCaptcha:
        pass
    if form.captcha:
        with open("out.jpg", "wb") as f:
            f.write(form.captcha["jpeg"].getbuffer())


client.login(EMAIL_ADDRESS, PASSWORD)

form = client.request_form(request_type=3)
if form.captcha:
    with open("out.jpg", "wb") as f:
        f.write(form.captcha["jpeg"].getbuffer())
captcha = input("Captcha please: ")

reference_number = form.submit(
    {
        "type_of_record_requested": "Employee Information",
        "describe_the_record_requested": "YOUR_REQUEST_TEXT",
        "member_of_the_media": "No",
        "preferred_method_to_receive_record": "Electronic via FOIA Center",
        "format": "PDF",
        "captcha": captcha,
    }
)


# List requests for the authenticated user
requests = client.list_requests()

for request in requests:
    # Get details of a specific request
    details = client.get_request(request["id"])
    print(details)

API

class govqa.GovQA(domain, *args, **kwargs)

Client for programmatically interacting with GovQA instances.

Parameters:

domain (str) – Root domain of the GovQA instance to interact with, e.g., https://governorny.govqa.us

new_account_form()

Get form for creating a new account

Returns:

an helper for creating a new account

Return type:

CreateAccountForm

login(username, password)

Login into the site

Parameters:

• username (str) – user name for thie site

• password (str) – password for thie site

request_form(request_type=1)

Get form for creating a new public record request

Parameters:

request_type (int) – Some site have more than one request type (i.e. commercial vs non-commercial). Indicates which one you want to use.

Returns:

an wrapper for creating a new record request

Return type:

RequestForm

list_requests()

Retrieve the id, reference number, and status of each request submitted by the authenticated account.

Returns:

List of dictionaries, each containing the id, reference number, and status of all requests.

Return type:

list

get_request(request_id)

Retrieve detailed information, included messages and attachments, about a request.

Parameters:

request_id (int) – Identifier of the request, i.e., the “id” from a request dictionary returned by list_requests(). N.b., the reference number is not the identifier.

Returns:

Dictionary of request metadata, correspondence, and attachments.

Return type:

dict

class govqa.base.CreateAccountForm(session)

Wrapper for interacting with a site’s account creation form

captcha

Dictionary of captcha jpeg and wav files as BytesIO objects, if the the form has a captcha. Otherwise, captcha has a value of None.

Type:

dict or None

schema

A JSON Schema representing the required fields to create an account and their format.

Type:

dict

submit(required_inputs)

Submit fields to create a new account. If the submission is unsuccessful, the captcha will be refreshed.

Parameters:

required_inputs (dict) – dictionary containing the field values for creating a new account. If the dictionary is not compatible with the schema then an informative error will be raised.

Returns:

Returns True if account created successfully

Return type:

bool

class govqa.base.RequestForm(session, request_type)

Wrapper for interacting with the site’s form to submit a new record request.

captcha

Dictionary of captcha jpeg and wav files as BytesIO objects, if the the form has a captcha. Otherwise, captcha has a value of None.

Type:

dict or None

schema

A JSON Schema representing the required fields to create a new record request.

Type:

dict

submit(required_inputs)

Submit fields to create a new record request. If the submission is unsuccessful, the captcha will be refreshed.

Parameters:

required_inputs (dict) – dictionary containing the field values for creating a new record request. If the dictionary is not compatible with the schema then an informative error will be raised.

Returns:

Returns the reference number if record request created successfully

Return type:

str