Skip to content

Latest commit

 

History

History
237 lines (181 loc) · 9.49 KB

api_keys.md

File metadata and controls

237 lines (181 loc) · 9.49 KB
Raw

API keys required for testing EVMap

EVMap uses multiple different data sources, most of which require an API key. These API keys need to be put into the app in the form of a resource file called apikeys.xml under app/src/main/res/values, with the following content:

apikeys.xml content 
<resources>
   <string name="google_maps_key" templateMergeStrategy="preserve" translatable="false">
      insert your Google Maps key here
   </string>
   <string name="mapbox_key" translatable="false">
      insert your Mapbox key here
   </string>
   <string name="jawg_key" translatable="false">
      insert your Jawg Maps key here
   </string>
   <string name="arcgis_key" translatable="false">
      insert your ArcGIS Maps key here
   </string>
   <string name="goingelectric_key" translatable="false">
      insert your GoingElectric key here
   </string>
   <string name="chargeprice_key" translatable="false">
      insert your Chargeprice key here
   </string>
   <string name="openchargemap_key" translatable="false">
      insert your OpenChargeMap key here
   </string>
   <string name="fronyx_key" translatable="false">
      insert your Fronyx key here
   </string>
   <string name="acra_credentials" translatable="false">
      insert your ACRA crash reporting credentials here
   </string>
</resources>

Not all API keys are strictly required if you only want to work on certain parts of the app. For example, you can choose only one of the map providers and one of the charging station databases. The Chargeprice API key is also only required if you want to test the price comparison feature.

Most APIs can be used for free, at least for testing. Some APIs require payment above a certain usage limit or to get access to the full dataset, but the free tiers should be plenty for local testing and development.

Below you find a list of all the services and how to obtain the API keys.

Map providers

The different Map SDKs are wrapped by our fork of the AnyMaps library to provide a common API. The google build flavor of the app includes both Google Maps and OpenStreetMap (vector tiles from Jawg Maps through MapLibre) and allows the user to switch between the two, while the foss flavor only includes OSM.

⚠️ When testing the app using the Android Emulator, we recommend using Google Maps and not OSM/MapLibre, as the latter has issues displaying the markers. It works fine on real Android devices.

Google Maps

Maps SDK for Android, Places API

How to obtain an API key
  1. Log in to the Google API console with your Google account
  2. Create a new project, or select an existing one that you want to use
  3. Under APIs & Services → Library, enable the Maps SDK for Android and Places API.
  4. Under APIs & Services → Credentials, click on Create credentials → API Key
  5. Copy the displayed key to your apikeys.xml file.

Jawg Maps

Dynamic Maps

How to obtain an API key
  1. Sign up for a Jawg account
  2. Under Access Tokens, copy your default access token or create a new one. Do not restrict it to a specific origin (this setting is not compatible with Android apps).

ArcGIS

World Imagery basemap
We use this for the satellite map, as Jawg's satellite style does not have global coverage.

How to obtain an API key
  1. Sign up for an ArcGIS developer account
  2. In the dashboard, copy your default API key or create a new one. It has to have access to the "Basemaps" service.

Mapbox

Geocoding API
previously we also used Mapbox's Maps SDK, but this has now been switched to Jawg Maps.

How to obtain an API key
  1. Sign up for a Mapbox account
  2. Under Access Tokens, create a new access token
  3. Set a name for the scope and enable only the preselected public scopes. Do not restrict the token to a specific URL (this setting is not compatible with Android apps)

Charging station databases

GoingElectric.de

GoingElectric.de provides an API for their community-maintained directory of charging stations. The website and data are mostly only available in German.

How to obtain an API key
  1. Sign up for an account in the GoingElectric.de forum. The registration page can be switched to English using the dropdown menu under "Sprache". Then, agree to the registration terms.
  2. Fill in your desired username, password and email address and submit the registration form. You do not need to fill the information under GoingElectric Usermap.
  3. Verify your account by clicking on the link in the email you received
  4. Log in to the GoingElectric forum
  5. Go to this link to request access to the API. This page is only available in German. You need to fill in the following data:
    • name / company (Name / Firma)
    • street address (Straße, Nr.)
    • postal code, town (Postleitzahl, Ort)
    • country (Land)
    • email address (E-Mail Adresse)
    • website (Webseite, optional)
    • phone number (Telefonnummer, optional)
    • name of the app (Name der App): EVMap
    • app website (Webseite der App): https://github.com/ev-map/EVMap
    • description (kurze Beschreibung der App): please explain that you would like to contribute to the development of EVMap and therefore need access to the GoingElectric.de API.
    • Referrer (Herkunft): leave this field blank!
  6. When your access to the API is approved, you can access the API console to retrieve your API key.

OpenChargeMap

API documentation

How to obtain an API key
  1. Sign up for an account at OpenChargeMap
  2. Go to the My Apps page and click Register an application
  3. Enter the name of the app (EVMap) and website (https://github.com/ev-map/EVMap), and in the description field describe that you would like to contribute to the development of EVMap and therefore need access to the OpenChargeMap API. Do not tick the List App in Public Showcase box. Then, click save.
  4. Your API key will appear on the My Apps page.

Pricing providers

Chargeprice.app

API documentation

How to obtain an API key

Since February 2022, the Chargeprice API is no longer available for free to new customers. However, you can use their staging API for free to test the Chargeprice features. This is already configured by default for the debug version of the app, so you can leave the chargeprice_key field in your new app/src/main/res/values/apikeys.xml file blank. Note that the staging API contains only a limited dataset, so it only outputs prices for certain charge point operators and payment plans (see here for details).

In case you want to pay for access to the full Chargeprice API, check out their API docs on GitHub and contact them at [email protected].

Availability data providers

fronyx

fronyx provides us predictions of charging station availability.

How to obtain an API key

The API is not publicly available, contact fronyx to get an API key and documentation.

If you don't want to test this functionality, simply leave the API key blank.

Crash reporting

Crash reporting for release builds is done using ACRA. This should not be needed for debugging. If you still want to try it out, you can host any compatible backend such as Acrarium yourself.