search

fhstp-mfg / geowahl-api

Provides data API for geo–political data for Web and provides data visualization views.
2 stars 1 forks source link

readme

alt tag

GeoWahl visualizes geo–political data for the Web, Smartphone (iOS and Android) and Smartwatch (Apple Watch and Android Wear).

Platform–specific projects can be found here:

API

This repository provides an API for geo–political data and data visualization views.

JSON Data

The following routes return a Content-Type: application/json response.

All Elections

/elections

Returns all available elections, plus the associated data from the states, parties and results web services.

Response example: /elections

{
  "elections": [
    {
      "id": 1,
      "slug": "bpw16a"
      "name": "BPW16 1. Wahlgang",

      "states": [ ... ], // also retrieved by: /{electionSlug}/states
      "parties": [ ... ], // also retrieved by: /{electionSlug}/parties
      "results": [ ... ] // also retrieved by: /{electionSlug}/results
    },
    ... // further elections
  ]
}

Election (single)

/{electionSlug}

Returns an available election for the provided electionSlug, plus the associated data from the states, parties and results web services.

Response example: /bpw16b

{
  "id": 2,
  "slug": "bpw16b"
  "name": "BPW16 2. Wahlgang",

  "states": [ ... ], // also retrieved by: /{electionSlug}/states
  "parties": [ ... ], // also retrieved by: /{electionSlug}/parties
  "results": [ ... ] // also retrieved by: /{electionSlug}/results
}

Election States

/{electionSlug}/states

Returns all available states for an election, specified by electionSlug.

Response example: /bpw16b/states

{
  "states": [
    {
      "id": 0,
      "slug": "results"
      "name": "Alle Bundesländer"
    },
    {
      "id": 1,
      "slug": "w",
      "name": "Wien"
    },
    ... // further states
  ]
}

Election Parties

/{electionSlug}/parties

Returns all parties for an election, specified by electionSlug.

NOTE Each party contains corresponding colors, which you can look up under the Parties Color Definition page.

Response example: /bpw16b/parties

{
  "parties": [
    {
      "name": "Hofer",
      "rgba": { "r": 14, "g": 66, "b": 142, "a": 1 },
      "hex": "#0E428E"
    },
    {
      "name": "VdB",
      "rgba": { "r": 120, "g": 175, "b": 53, "a": 1 },
      "hex": "#78AF35"
    }
  ]
}

State Results

/{electionSlug}/{stateSlug}

Returns the total results for the provided stateSlug.

NOTE When stateSlug is set to results, then the total results of all available states are returned.

NOTE The results arrays always contain the following props:

Response example: /bpw16b/results or /bpw16b/w

{
  "results": [
    {
      "name": "Hofer",
      "votes": {PARTY_VOTES},
      "percent": {PARTY_PERCENT_ROUNDED},
      "exact": {PARTY_PERCENT_EXACT}
    },
    {
      "name": "VdB",
      "votes": {PARTY_VOTES},
      "percent": {PARTY_PERCENT_ROUNDED},
      "exact": {PARTY_PERCENT_EXACT}
    }
  ]
}

State Districts

/{electionSlug}/{stateSlug}/districts

Returns all districts and the corresponding results for the provided electionSlug and stateSlug.

NOTE The results array format stays the same.

Response example: /bpw16a/w/districts

{
  "districts": [
    {
      "id": 1,
      "name": "Innere Stadt",
      "results": [ ... ]
    },
    ... // further districts
  ]
}

NOTE If stateSlug is set to results (see example below), then the total results of each available state are returned. In this case the property districts will actually contain an array of states and the total results for each corresponding state.

Response example: /bpw16b/results/districts

{
  "districts": [
    {
      "name": "Wien",
      "results": [
        {
          "name": "Hofer",
          "votes": {PARTY_TOTAL_VOTES},
          "percent": {PARTY_TOTAL_PERCENT_ROUNDED},
          "exact": {PARTY_TOTAL_PERCENT_EXACT}
        },
        {
          "name": "VdB",
          "votes": {PARTY_TOTAL_VOTES},
          "percent": {PARTY_TOTAL_PERCENT_ROUNDED},
          "exact": {PARTY_TOTAL_PERCENT_EXACT}
        }
      ]
    },
    ... // further districts
  ]
}

District Results by id

/{electionSlug}/{stateSlug}/{districtId}

All–In–One – Returns the results for a district, specified by districtId. Furthermore it returns the results for the parent state, specified by stateSlug, and the results for the election, specified by electionSlug.

NOTE The results array format stays the same.

Response example: /bpw16b/w/1

{
  "district": {
    "id": 1,
    "name": "Innere Stadt",
    "results": [ ... ]
  },

  "state": {
    "slug": "w",
    "name": "Wien",
    "results": [ ... ]
  },

  "election": {
    "slug": "bpw16b",
    "name": "BPW16 2. Wahlgang",
    "results": [ ... ]
  }
}

District Results by Geolocation

/{electionSlug}/{latitude},{longitude}

All–In–One – Searches for a district by latitude and longitude and returns the corresponding district results. Furthermore it returns the results for the parent state, specified by stateSlug, and the results for the election, specified by electionSlug.

NOTE The results array format stays the same.

Response example: /bpw16b/48.014223,16.5558545

{
  "district": {
    "id": 75,
    "name": "Götzendorf an der Leitha",    
    "results": [ ... ]
  },

  "state": {
    "slug": "noe",
    "name": "Niederösterreich",
    "results": [ ... ]
  },

  "election": {
    "slug": "bpw16b"
    "name": "BPW16 2. Wahlgang",
    "results": [ ... ]
  }
}

Visualizations

The following routes return Content-Type: text/html views using D3 for visualizing data.

Election Results Donut–Chart

/{electionSlug}/donut-chart

Election Results Donut–Chart Visualization

State Results Donut–Chart

/{electionSlug}/{stateSlug}/donut-chart

(State Results Donut–Chart Visualization example coming soon ...)

District Results Donut–Chart

/{electionSlug}/{stateSlug}/{districtId}/donut-chart

(District Results Donut–Chart Visualization example coming soon ...)

Using Google APIs

Setup

In order to use Google APIs, you have to add your own Server API key.

  1. Go to the Google Developer Console

  2. From the project drop-down, select an existing project, or create a new one by selecting Create a new project.

  3. In the sidebar under "API Manager", select Credentials, then select the OAuth consent screen tab.

    • Choose an Email Address, specify a Product Name (e.g. "GeoWahl"), and press Save.

  4. In the Credentials tab, select the New credentials drop-down list, and choose API key.

  5. In the Create a new key dialog box select Server key.

  6. Specify a Name for the Server key (e.g. "GeoWahl Server").

    • Optionally you can limit requests to a list of IP addresses.

  7. Finally press the Create button.

NOTE It may take up to 5 minutes for settings to take effect.

Activate APIs

The following Google APIs have to be activated:

In the sidebar under "API Manager", select Google APIs, the search and select the afore mentioned APIs and press the Enable button.

Usage

  1. In the sidebar under "API Manager", select Credentials, then copy your key from the API keys section.

  2. Change the environment variable API_KEY in your .env file to your selected API key.

Available Data

Austrian presidential elections (Bundespräsidentenwahlen 2016)

The results for all the federal states and communities from both ballots are available to the full extent !

Austrian representatives elections (Nationalratswahlen 2013)

The results for all the federal states and communities are available. Only the state Steiermark is missing, since they don't provide any useful .csv files for their result. You are happily invited to add this !

Austrian local elections (Gemeinderatswahlen 2013)

The community results for the states Burgenland, Niederösterreich, Oberösterreich, Salzburg and Vienna are available. There is no data for the states Steiermark, Kärnten, Vorarlberg and Tirol.

Data errors

Data errors should not be excluded, as all files have been curated to .json format manually.

We assume no liability for possible mistakes !

Contributors

License

The MIT License (MIT)

that's all folks