diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2a04cd2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# Python3 ÖBB API
+
+This project aims to provide a functional API for the Austrian Federal Railways
+(Österreichische Bundesbahnen, ÖBB). It has three core features/request types:
+
+* Search for Public Transportation stops by name ("val")
+* Search for Public Transportation stops by coordinates ("nearby")
+* Search for Public Transportation connections between two stops ("conn")
+
+## Request
+
+A request is made by sending a GET or POST request to the endpoint, e.g.
+[https://bahnapi.xyz/](https://bahnapi.xyz), with a "type" parameter and
+additional parameters as required for the request type.
+
+The example requests below use GET for obvious reasons, but passing the same
+parameters in a POST request will yield the same results.
+
+### Search for stops by name ("val")
+
+The following parameters are required for this type of request:
+
+* "type": "val"
+* "name": Name of the station
+
+This request will return a list of station names most closely matching the name
+provided in the request as well as corresponding station IDs, ordered by match
+quality.
+
+* [Example "val" request](https://bahnapi.xyz/?type=val&name=Graz)
+
+### Search for stops by coordinates ("nearby")
+
+The following parameters are required for this type of request:
+
+* "type": "nearby"
+* "lat": Decimal latitude
+* "lon": Decimal longitude
+
+The following optional parameter is accepted:
+
+* "distance": Maximum distance in meters (as the crow flies, default: 1000)
+
+This request will return a list of station names closest to given coordinates
+as well as the corresponding station IDs and distance in meters (as the crow
+flies), ordered by distance.
+
+The "distance" parameter defaults to 1000, i.e. stations up to 1,000 meters from
+the provided coordinates will be returned. You may want to increase or decrease
+this value, but setting it too high may cause the request to time-out.
+
+This makes a request to [OpenStreetMap](https://osm.org/) to find the stations
+closest to given coordinates. Issues may occur where station names in OSM differ
+from those used internally by ÖBB.
+
+* [Example "nearby" request]
+(https://bahnapi.xyz/?type=nearby&lat=47.489&lon=9.69)
+
+### Search for connections between two stops ("conn")
+
+The following parameters are required for this type of request:
+
+* "type": "conn"
+* "from": Name or ID (as returned by "val") of the station of departure
+* "to": Name or ID of the station of arrival
+
+The following optional parameters are accepted:
+
+* "count": Number of connections to return (default: 1)
+* "date": Date on which to find a connection (e.g. 31.12.2017, default: today)
+* "time": Time at which to find a connection (e.g. 20:00, default: current time)
+* "mode": May be set to "arr" if "time" should be considered time of arrival
+* "details": May be set to return additional details to connections (see below)
+
+This request will return a list of connections between the two stations given in
+the "from" and "to" parameters, ordered by time of departure.
+
+It is not required that the station names provided in "from" and "to" exactly
+match the stations' official names. A "val" request will always be made
+implicitly and the closest match will be used.
+
+* [Example "conn" request from "Leibitz" to "Kaldorf"]
+(https://bahnapi.xyz/?type=conn&from=Leibitz&to=Kaldorf)
+
+By default, the response will not include some information, including at which
+stations a change to a different service is required, if applicable. It will,
+however, return the total number of changes. If additional information is
+required, it may be requested by adding the "details" parameter to the request.
+Note that this request is going to take considerably longer to process. If at
+all possible, do not set "count" higher than 1 when requesting details as too
+many connections may cause the query to time-out.
+
+* [Example "conn" request without details]
+(https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien)
+* [Same request with details]
+(https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien&details)
+
+If "count" is not set, one connection will be returned. This value may safely be
+increased up to 6 if "details" is not set.
+
+* [Example "conn" request for five connections]
+(https://bahnapi.xyz/?type=conn&from=Thörl&to=Pama&count=5)
+
+The provided "time" will by default be considered as the requested time of
+departure. To use it as the time of arrival instead, the "mode" parameter may
+be set to "arr".
+
+* [Example "conn" request using time of departure]
+(https://bahnapi.xyz/?type=conn&from=Wolkersdorf im Weinviertel&to=
+Götzendorf/Leitha&time=12:00)
+* [Same request using time of arrival]
+(https://bahnapi.xyz/?type=conn&from=Wolkersdorf im Weinviertel&to=
+Götzendorf/Leitha&time=12:00&mode=arr)
+
+### Short requests
+
+For "val" and "conn" requests, it is possible to use shorter requests by passing
+arguments in the path. Paths consisting of one part (i.e. /value) will be
+handled as "val" requests while those consisting of two parts (/value1/value2)
+will be handled as "conn" requests. Optional values can be passed as GET or POST
+parameters as usual.
+
+* [Example short "val" request](https://bahnapi.xyz/Kanfanar)
+* [Example short "conn" request](https://bahnapi.xyz/Bregenz/Neusiedl am See)
+
+### Output format
+
+By default, the API returns its results as XML. If you prefer JSON, you may add
+the "json" parameter to your query.
+
+* [Example "nearby" request returning JSON]
+(https://bahnapi.xyz/?type=nearby&lat=48.293&lon=16.482&json)
\ No newline at end of file