shamilkhan / elections-us-backend Goto Github PK

🇺🇸 US Elections API: Get election data on candidates, parties, states, counties, and cities. 🗳️ Built with Node.js, TypeScript, and PostgreSQL, it has endpoints for data retrieval and a data model including entities like Election 🗓️, Candidate 🙋, and Party 🎉.

Home Page: https://elections-us.netlify.app/

JavaScript 2.26% TypeScript 97.74%

api elections postgis postgresql typeorm typescript

elections-us-backend's Introduction

🗳️ US Elections API

This project provides an API for accessing data on US elections. The API is built with Node.js, TypeScript, and PostgreSQL, and is powered by the Express.js framework.

🚀 Getting Started

To get started with the API, follow these steps:

Clone the repository: git clone https://github.com/example/us-elections-api.git.
Install dependencies using yarn: yarn install.
Run database migrations: yarn run typeorm migration:run.
Start the server: yarn start.

Once the server is running, you can access the API at http://localhost:3000.

🔗 API Endpoints

The following endpoints are available:

`/api/v1/elections`

GET /api/v1/elections: Returns a list of all elections.
GET /api/v1/elections/:id: Returns details of a specific election.

`/api/v1/candidates`

GET /api/v1/candidates: Returns a list of all candidates.
GET /api/v1/candidates/:id: Returns details of a specific candidate.

`/api/v1/parties`

GET /api/v1/parties: Returns a list of all parties.
GET /api/v1/parties/:id: Returns details of a specific party.

`/api/v1/states`

GET /api/v1/states: Returns a list of all states.
GET /api/v1/states/:id: Returns details of a specific state.
GET /api/v1/states/:id/election-results: Returns the election results for a specific state.

`/api/v1/counties`

GET /api/v1/counties: Returns a list of all counties.
GET /api/v1/counties/:id: Returns details of a specific county.
GET /api/v1/counties/:id/election-results: Returns the election results for a specific county.

`/api/v1/cities`

GET /api/v1/cities: Returns a list of all cities.
GET /api/v1/cities/:id: Returns details of a specific city.
GET /api/v1/cities/:id/election-results: Returns the election results for a specific city.

🗂️ Data Model

The data model for the API is as follows:

Election: Represents an election, with a name, year, type, start date, and end date.
Candidate: Represents a candidate, with a name and a party affiliation.
Party: Represents a political party, with a name.
State: Represents a US state, with a name, number of electoral votes, and geographic boundary.
County: Represents a county within a US state, with a name, geographic boundary, and reference to its parent state.
City: Represents a city within a US state and county, with a name, geographic boundary, and references to its parent state and county.
StateElectionResult: Represents the election results for a specific state, with a reference to the election, state, winner, total votes, and a breakdown of votes by candidate.
CountyElectionResult: Represents the election results for a specific county, with a reference to the election, county, winner, total votes, and a breakdown of votes by candidate.
CityElectionResult: Represents the election results for a specific city, with a reference to the election, city,

elections-us-backend's People

Contributors

Watchers

Forkers

bendgomin333 electionsdata

elections-us-backend's Issues

Create a migration to upload 2020 Election data

To upload the 2020 Election data, you need to create a migration. The data source is available here.

To upload data with a migration, create a "migrations" folder that contains the .CSV files. Follow these steps for the migration:

Create a new migration file:

nest generate migration uploadElectionData

Update the migration file to include the COPY command for each CSV file:

// src/migrations/xxxxxxx-upload-election-data-2020.ts
import { MigrationInterface, QueryRunner } from 'typeorm';

export class uploadElectionData2020xxxxxxx implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    // Make sure the CSV files are accessible by the PostgreSQL server
    await queryRunner.query(`
      COPY states (id, name, electoral_votes, boundary) FROM '<path_to_csv_files>/states.csv' WITH (FORMAT csv, HEADER true);
      COPY counties (id, name, state_id, boundary) FROM '<path_to_csv_files>/counties.csv' WITH (FORMAT csv, HEADER true);
      COPY cities (id, name, state_id, county_id, boundary) FROM '<path_to_csv_files>/cities.csv' WITH (FORMAT csv, HEADER true);
      COPY parties (id, name) FROM '<path_to_csv_files>/parties.csv' WITH (FORMAT csv, HEADER true);
      COPY candidates (id, name, party_id) FROM '<path_to_csv_files>/candidates.csv' WITH (FORMAT csv, HEADER true);
      COPY elections (id, name, year, type, start_date, end_date) FROM '<path_to_csv_files>/elections.csv' WITH (FORMAT csv, HEADER true);
      COPY state_election_results (id, election_id, state_id, winner_id, total_votes, candidate_votes) FROM '<path_to_csv_files>/state_election_results.csv' WITH (FORMAT csv, HEADER true);
      COPY county_election_results (id, election_id, county_id, winner_id, total_votes, candidate_votes) FROM '<path_to_csv_files>/county_election_results.csv' WITH (FORMAT csv, HEADER true);
      COPY city_election_results (id, election_id, city_id, winner_id, total_votes, candidate_votes) FROM '<path_to_csv_files>/city_election_results.csv' WITH (FORMAT csv, HEADER true);
    `);
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    // Remove data from the tables
    await queryRunner.query(`
      TRUNCATE city_election_results, county_election_results, state_election_results, elections, candidates, parties, cities, counties, states;
    `);
  }
}

Add historical data support

To support historical data for states, cities, and counties with valid from and valid patterns, you can add two fields to your existing schema: validFrom and validTo. These fields will indicate the time period during which a particular state, city, or county was valid. Example of state:

CREATE TABLE states (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  valid_from DATE NOT NULL,
  valid_to DATE NOT NULL
);

Add Swagger

https://docs.nestjs.com/openapi/introduction

Add Rate Limiting

https://docs.nestjs.com/security/rate-limiting

shamilkhan / elections-us-backend Goto Github PK

elections-us-backend's Introduction

🗳️ US Elections API

🚀 Getting Started

🔗 API Endpoints

/api/v1/elections

/api/v1/candidates

/api/v1/parties

/api/v1/states

/api/v1/counties

/api/v1/cities