Skip to content

Commit

Permalink
added elections object docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@diafygi
diafygi committed May 17, 2018
1 parent 45c52b2 commit 19a51e0
Show file tree
Hide file tree
Showing 3 changed files with 339 additions and 6 deletions.
335 changes: 334 additions & 1 deletion website/docs/templates/docs/api_elections_object.html
View file
Expand Up @@ -9,6 +9,339 @@
<h1>
Elections
</h1>
{# TODO #}
<p>
Election objects contain general details about a particular election,
such as election type, date, a short description, and any particular
overall requirements for the election. Additionally, you can optionally
<a href="{% url 'docs:api_elections_list' %}#include">include</a> the
particular <a href="{% url 'docs:api_contests_object' %}">Contests</a> or
<a href="{% url 'docs:api_precincts_object' %}">Precincts</a> for an Election.
</p>
<p>
<a href="#examples">See examples of Election objects.</a>
</p>

<h3 id="api-endpoints" class="permalink-wrapper">
API Endpoints
<a href="#api-endpoints" class="permalink"></a>
</h3>
<ul class="list-unstyled">
<li>
<a href="{% url 'docs:api_elections_list' %}">
<span class="label label-success">GET</span>
<code>/elections</code></a> -
List elections (can be searched and filtered).
</li>
<li>
<a href="{% url 'docs:api_elections_get' %}">
<span class="label label-success">GET</span>
<code>/elections/<em>{id}</em></code></a> -
Get a specific election.
</li>
</ul>

<hr>

<h2 id="attributes" class="permalink-wrapper">
Attributes
<a href="#attributes" class="permalink"></a>
</h2>
<div class="table-responsive">
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Attribute</th>
<th>Format</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td id="type" class="permalink-wrapper">
<code>type</code>
<a href="#type" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#object-type">ObjectType</a>
</td>
<td>
This object's data type. Will always be "election".
</td>
<td>
<code>"election"</code>
</td>
</tr>
<tr>
<td id="id" class="permalink-wrapper">
<code>id</code>
<a href="#id" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#string">String</a>
</td>
<td>
This is the unique id we assign to the Election. This is
the id used in
<a href="{% url 'docs:api_contests_object' %}#election_id">Contest.election_id</a>
and
<a href="{% url 'docs:api_precincts_object' %}#election_id">Precinct.election_id</a>.
</td>
<td>
<code>"a74635..."</code>
</td>
</tr>
<tr>
<td id="election_type" class="permalink-wrapper">
<code>election_type</code>
<a href="#election_type" class="permalink"></a>
</td>
<td>
<a href="#election-types">ElectionType</a>
</td>
<td>
This is the type of election (e.g. general, primary, etc.).
See the full list of <a href="#election-types">Election Types</a>
for possible values and what they mean.
</td>
<td>
<code>"general"</code>
</td>
</tr>
<tr>
<td id="election_name" class="permalink-wrapper">
<code>election_name</code>
<a href="#election_name" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#string">String</a>
</td>
<td>
This is a short display name for the election. We try to
keep it under 10 words.
</td>
<td>
<code>"2018 Midterm Election"</code>
</td>
</tr>
<tr>
<td id="date" class="permalink-wrapper">
<code>date</code>
<a href="#date" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#date">Date</a>
</td>
<td>
This is the official election date. NOTE: Since polling
hours vary by location, we put those specific dates and
times (with local timezones) in the
<a href="{% url 'docs:api_precincts_object' %}#voting_times">Precinct.voting_times</a>
attribute.
</td>
<td>
<code>"2018-05-15"</code>
</td>
</tr>
<tr>
<td id="short_info" class="permalink-wrapper">
<code>short_info</code>
<a href="#short_info" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#string">String</a>
</td>
<td>
This is a short description for the election. We try to
keep it to a single sentence under 25 words.
</td>
<td>
<code>"This is a major national election that happens every two years to elect many federal, state, and local positions."</code>
</td>
</tr>
<tr>
<td id="contests" class="permalink-wrapper">
<code>contests</code>
<a href="#contests" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#response">Response</a>
</td>
<td>
<strong>
(only if
<a href="{% url 'docs:api_elections_list' %}#include">included</a>)
</strong>
These are the
<a href="{% url 'docs:api_contests_object' %}">Contests</a>
that are part of this Election.
NOTE: This response list can be paginated, so be sure
to know how to handle
<a href="{% url 'docs:data_types' %}#response-attributes-next">paginated responses</a>.
</td>
<td>
<code>{"type": "response", "data": [...], ...}</code>
</td>
</tr>
<tr>
<td id="precincts" class="permalink-wrapper">
<code>precincts</code>
<a href="#precincts" class="permalink"></a>
</td>
<td>
<a href="{% url 'docs:data_types' %}#response">Response</a>
</td>
<td>
<strong>
(only if
<a href="{% url 'docs:api_elections_list' %}#include">included</a>)
</strong>
These are the
<a href="{% url 'docs:api_precincts_object' %}">Precincts</a>
that are part of this Election.
NOTE: This response list can be paginated, so be sure
to know how to handle
<a href="{% url 'docs:data_types' %}#response-attributes-next">paginated responses</a>.
</td>
<td>
<code>{"type": "response", "data": [...], ...}</code>
</td>
</tr>
</tbody>
</table>
</div>

<hr>

<h2 id="examples" class="permalink-wrapper">
Examples
<a href="#examples" class="permalink"></a>
</h2>
<h5 id="example-general-election" class="permalink-wrapper">
A general election:
<a href="#example-general-election" class="permalink"></a>
</h5>
<pre>
{
"type": "election",
"id": "123-4",
"election_type": "general",
"election_name": "Midterm Election",
"date": "2018-11-05",
"short_info": "This is a major national election that happens every two years to elect many federal, state, and local positions."
}
</pre>
<h5 id="example-special-election" class="permalink-wrapper">
A primary election:
<a href="#example-special-election" class="permalink"></a>
</h5>
<pre>
{
"type": "election",
"id": "3983-b823",
"election_type": "primary",
"election_name": "California Primary Election",
"date": "2018-06-05",
"short_info": "This is a major primary election for political parties in California."
}
</pre>
<h5 id="example-special-election" class="permalink-wrapper">
A special election:
<a href="#example-special-election" class="permalink"></a>
</h5>
<pre>
{
"type": "election",
"id": "339-83az",
"election_type": "special",
"election_name": "Arizona 8th U.S. Congressional District Special Election",
"date": "2018-04-24",
"short_info": "This is a special election to fill the vacant Arizona 8th U.S. Congressional District seat."
}
</pre>

<hr>

<h2 id="election-types" class="permalink-wrapper">
Election Types
<a href="#election-types" class="permalink"></a>
</h2>
<p>

</p>
<div class="table-responsive">
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Election Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td id="election-type-general" class="permalink-wrapper">
<code>general</code>
<a href="#election-type-general" class="permalink"></a>
</td>
<td>
A regularly-scheduled general election with many contests
covering multiple states.
</td>
</tr>
<tr>
<td id="election-type-state" class="permalink-wrapper">
<code>state</code>
<a href="#election-type-state" class="permalink"></a>
</td>
<td>
A regularly-scheduled state election covering all or the
majority of a single state.
</td>
</tr>
<tr>
<td id="election-type-local" class="permalink-wrapper">
<code>local</code>
<a href="#election-type-local" class="permalink"></a>
</td>
<td>
A regularly-scheduled local election convering all or the
majority of a local municipality or region.
</td>
</tr>
<tr>
<td id="election-type-primary" class="permalink-wrapper">
<code>primary</code>
<a href="#election-type-primary" class="permalink"></a>
</td>
<td>
A regularly-scheduled election for political parties
(can be for one or more political party).
</td>
</tr>
<tr>
<td id="election-type-special" class="permalink-wrapper">
<code>special</code>
<a href="#election-type-special" class="permalink"></a>
</td>
<td>
A non-regularly-scheduled (e.g. one-time) election for
a specific contest.
</td>
</tr>
<tr>
<td id="election-type-special-primary" class="permalink-wrapper">
<code>special_primary</code>
<a href="#election-type-special-primary" class="permalink"></a>
</td>
<td>
A non-regularly-scheduled (e.g. one-time) primary election
for political parties (can be for one or more political party).
</td>
</tr>
</tbody>
</table>
</div>


{% endblock %}

6 changes: 3 additions & 3 deletions website/docs/templates/docs/info_data_types.html
View file
Expand Up @@ -500,16 +500,16 @@ <h2 id="datetime" class="permalink-wrapper">
ISO-8601
<small class="glyphicon glyphicon-new-window"></small></a>
combined date and time with timezone (e.g. <code>YYYY-MM-DDTHH:MM:SS+00:00</code>).
All API response datetimes are in UTC. If you provide a datetime in
All API response datetimes have a timezone. If you provide a datetime in
a request parameter, be sure to specify the timezone offset (so we can
convert it to UTC).
know how to compare it to other datetimes).
</p>
<h4 id="datetime-example" class="permalink-wrapper">
DateTime Example
<a href="#datetime-example" class="permalink"></a>
</h4>
<pre>
"2018-01-23T04:55:12+00:00"
"2018-01-23T22:55:12-08:00"
</pre>


Expand Down
4 changes: 2 additions & 2 deletions website/docs/templates/docs/info_quickstart.html
View file
Expand Up @@ -58,10 +58,9 @@ <h3 id="step-1" class="permalink-wrapper">
"type": "election",
"id": "123-4",
"election_type": "..."
"election_name": "...",
"date": "...",
"short_info": "...",
"long_info": "...",
"restrictions": [...],
"contests": {
"type": "response",
"data": [
Expand Down Expand Up @@ -143,6 +142,7 @@ <h3 id="step-2" class="permalink-wrapper">
"type": "precinct",
"id": "345-6",
"election_id": "123-4",
"voting_times": {...},
"geo": {"type": "Polygon", ...},
},
...
Expand Down

0 comments on commit 19a51e0

Please sign in to comment.