Paqle Election API

The purpose of this API is to make the candidates, questionnaires and elections available as JSON.

The API is accessed via HTTPS GET requests and responds with UTF-8 encoded JSON when successful. When an error occurs, the relevant HTTP status code is used. Each API request must provide an HTTP Basic Authorization header, eg:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

If this header is missing or the credentials are wrong, it results in a 401 status code and no data.

https://electionapi.paqle.net/{endpoint}/candidates

On this URL you'll find updates to candidates and their questionnaire submissions. Use this to maintain your own local index of candidates for the elections and questionnaires we've agreed to cover.

The response contains a Mark field, whose value can be used to get the next page of updates via the query parameter ?mark={mark}. Continue until you reach a page with no updates. Once you reach that point, start polling for updates at an interval of 1+ minutes.

You can also use the query parameter ?limit={limit} to control how many candidates are returned per page. Valid values are in the range 0 to 1000.

The response contains an ImageIds convenience field, containing all the textual identifiers for images that occur in the Updates. The images can be fetched from the images URL below. Use this to maintain your own local image mirror.

To find a specific candidate in the API, use the query parameter ?originalId={originalId}.

The Updates field contains a list of persons. The OriginalId is the ID of the person. The CurrentId is a version number for the person. The MergedIds is the IDs of persons that have been merged into this person. If you have any of these IDs in your index, they should be deleted or become redirects to the OriginalId. The Sections contain data about the person. Each section may have multiple records - if you only need e.g. a single name or a single email, then pick the first record. The Opinions contain the latest submission (if any) for the person for each questionnaire.

Each submission under Opinions has a Submitted time expressed as milliseconds after 1970-01-01T00:00:00Z (i.e. UNIX time in milliseconds), as well as an Answers field containing the latest answers, each with the following fields:

• Id: The unique ID for the question. Use this field to identify which question was answered.
• Version: The precise version of the question. Useful if questions have changed over time.
• Choices: The predefined choice(s) picked by the candidate (in order of priority for prioritized choices). Each choice is an object with an Id field and for allocation questions, also a numeric Value field. Will be missing when no predefined choices are picked.
• Text: The textual answer given by the candidate. Will be missing if no textual answer is given.
• Comment: A comment tied to the answer. This field is optional and will be missing frequently.

A person is considered a candidate for an election when there is an object in the Sections.Elections array where ElectionReference.OriginalId contains the given election ID and IsCandidate is true. In addition, the object may contain:

• ListCode, which represents the letter (sometimes multiple letters and digits) printed on the ballot identifying a party or local list of candidates.
• ListName, which is the name of the party or local list.
• ListArea, which is the area in which the candidate runs.
• ListPosition, which is used to specify the candidates position on the list. Only used for certain elections.
• PartyReference, which, if the candidate runs for a national party, refers by OriginalId to an entity representing that party.
• IsPrimaryCandidate, which is true when the candidate is considered a primary candidate in the area for the party or local list. Only used for certain elections.
• ListTotalVotes, which holds the combined number of votes the party or local list got in that list area.
• PersonalVotes, which holds the personal votes this candidate got in that list area.
• Elected, which is true if the candidate made the cut for inclusion in the parliament / regional board / local board.

Persons never leave the API once they're in it. Instead, they're marked as Hidden if they're no longer a candidate for any of the relevant elections.

https://electionapi.paqle.net/{endpoint}/images/{imageId}

On this URL you can download images. When candidates upload a photo, they're asked to crop the image to a square, which we store as a 1200x1200 JPEG. Logos and photos uploaded by our staff may have different dimensions or be PNGs.

https://electionapi.paqle.net/{endpoint}/elections

On this URL you'll find the elections with list areas, parties and lists.

https://electionapi.paqle.net/{endpoint}/questionnaires

On this URL you'll find the questions from the questionnaires. Each question has an Id and one or more Versions:

• Version: The precise version of the question.
• Position: Questions will be presented in ascending order of their position. Questions with the same position will be shuffled amongst each other. Must be at least 1.
• Scopes: The scopes of the question, used to only ask certain entities this question. This field will be missing when there's no scope.
• Topic: The topic of the question. This field will be missing when there's no topic.
• Framing: An optional framing text for the question.
• Statement: The phrasing of this version of the question.
• Background: An optional explanation of the question.
• Type: The type of question.
• Choices: Predefined choices that the candidate can pick from. Each choice is an object with the fields Id, Label and for allocation questions, a numeric Default value.
• MinChoices: The minimum number of choices that can be selected by an entity. Must be at least 1.
• MaxChoices: The maximum number of choices that can be selected by an entity. If this is 1, radio buttons will be presented instead of checkboxes.
• MinText: If the candidate answers with text, it must contain at least this many characters. A textual answer counts as a choice for the purposes of MinChoices/MaxChoices.
• MaxText: If the candidate answers with text, it must contain at most this many characters. Use 0 to disable textual answers.
• MaxComment: The maximum length of the optional comment. Use 0 to disable comments.
• AskCandidate: This field is true when candidates will be asked this question, and false otherwise.
• AskVoter: This field is true when voters will be asked this question, and false otherwise.
• Deleted: The time when this version of the question was replaced by a new version or deleted, as milliseconds after 1970-01-01T00:00:00Z (i.e. UNIX time in milliseconds). This field is missing for the active version of the question.