# Practical guide

This guide is intended for prospective and current API customers of Ballotpedia. We want to make it easy for you to understand and use the data we provide in our API; this document gives concrete examples for some real-world applications you might want to build using the API.

## Sample Ballot Application <a href="#sample-ballot" id="sample-ballot"></a>

Suppose you want to provide a sample ballot lookup on your website. This can be accomplished by the following steps:

1. Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates.
2. With the user's lat/long, query the `/election_dates` endpoint.
3. With the user's lat/long and chosen election date, pass these parameters to the `/elections_by_point` endpoint.
4. Finally, display the results. Exactly how to do this is up to you, but now you have all the data you need to do it. You can loop over the districts, races, and candidates and display their names, party affiliations, link to their Ballotpedia profile, status, and much more.

[*Click here to view Ballotpedia's Sample Ballot Tool*](https://ballotpedia.org/Sample_Ballot_Lookup)

## Current Representatives Application <a href="#representatives" id="representatives"></a>

Suppose you want to allow users to look up their current elected officials. This can be accomplished by the following steps:

1. Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates.
2. Fetch the elected officials for the user’s location. Supply the latitude/longitude coordinates from the previous step into the `/officeholders` endpoint.
3. Display the results. This part is up to you, but now you have all the data you need to do it. You can loop over the districts, offices, and officeholders and display their names, party affiliations, link to their Ballotpedia profile, contact information, and much more.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.ballotpedia.org/geographic-apis/practical-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.