Skip to content

Commit 8e5be1b

Browse files
dh--dh--
committed
Merge pull request googlemaps#26 from googlemaps/ReadMe
Updating the ReadMe file with some simple comments and examples
2 parents d3226c8 + 760c79c commit 8e5be1b

1 file changed

Lines changed: 144 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 144 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,152 @@
1-
Generating documentation:
1+
Python Client for Google Maps Services
2+
====================================
23

3-
$ sphinx-build -b html docs docs/html
4+
## Description
5+
6+
Use Python? Want to [geocode][Geocoding API] something? Looking for [directions][Directions API]?
7+
Maybe [matrices of directions][Distance Matrix API]? This library brings the [Google Maps API Web
8+
Services] to your Python application.
9+
10+
The Python Client for Google Maps Services is a Python Client library for the following Google Maps
11+
APIs:
12+
13+
- [Directions API]
14+
- [Distance Matrix API]
15+
- [Elevation API]
16+
- [Geocoding API]
17+
- [Time Zone API]
18+
19+
Keep in mind that the same [terms and conditions](https://developers.google.com/maps/terms) apply
20+
to usage of the APIs when they're accessed through this library.
21+
22+
## Support
23+
24+
This library is community supported. We're comfortable enough with the stability and features of
25+
the library that we want you to build real production applications on it. We will make an effort to
26+
support the public and protected surface of the library and maintain backwards compatibility in the
27+
future; however, while the library is in version 0.x, we reserve the right to make
28+
backwards-incompatible changes. If we do remove some functionality (typically because better
29+
functionality exists or if the feature proved infeasible), our intention is to deprecate and
30+
provide ample time for developers to update their code.
31+
32+
If you find a bug, or have a feature suggestion, please [log an issue][issues]. If you'd like to
33+
contribute, please read [How to Contribute][contrib].
34+
35+
## Requirements
36+
37+
- Python 2.7 or later.
38+
- A Google Maps API key.
39+
40+
### API keys
441

5-
Installing dependencies:
42+
Each Google Maps Web Service requires an API key or Client ID. API keys are
43+
freely available with a Google Account at https://developers.google.com/console.
44+
To generate a server key for your project:
645

46+
1. Visit https://developers.google.com/console and log in with
47+
a Google Account.
48+
1. Select an existing project, or create a new project.
49+
1. Click **Enable an API**.
50+
1. Browse for the API, and set its status to "On". The Python Client for Google Maps Services
51+
accesses the following APIs:
52+
* Directions API
53+
* Distance Matrix API
54+
* Elevation API
55+
* Geocoding API
56+
* Time Zone API
57+
1. Once you've enabled the APIs, click **Credentials** from the left navigation of the Developer
58+
Console.
59+
1. In the "Public API access", click **Create new Key**.
60+
1. Choose **Server Key**.
61+
1. If you'd like to restrict requests to a specific IP address, do so now.
62+
1. Click **Create**.
63+
64+
Your API key should be 40 characters long, and begin with `AIza`.
65+
66+
**Important:** This key should be kept secret on your server.
67+
68+
## Installation
69+
70+
# Installing dependencies:
771
$ pip install requests responses
872

9-
Running tests:
73+
## Developer Documentation
74+
75+
Additional documentation for the included web services is available at
76+
https://developers.google.com/maps/.
77+
78+
- [Directions API]
79+
- [Distance Matrix API]
80+
- [Elevation API]
81+
- [Geocoding API]
82+
- [Time Zone API]
83+
84+
## Usage
85+
86+
This example uses the [Geocoding API].
87+
88+
89+
90+
```python
1091

92+
ctx = googlemaps.Context('Add Your Key here')
93+
94+
# Geocoding and address
95+
geocode_result = googlemaps.geocode(ctx, '1600 Amphitheatre Parkway, '
96+
'Mountain View, CA')
97+
98+
# Look up an address with reverse geocoding
99+
reverse_geocode_result = googlemaps.reverse_geocode(ctx, (40.714224, -73.961452))
100+
101+
# Request directions via public transit
102+
now = datetime.now()
103+
directions_result = googlemaps.directions(ctx,
104+
"Sydney Town Hall",
105+
"Parramatta, NSW",
106+
mode="transit",
107+
departure_time=now)
108+
```
109+
110+
111+
112+
For more usage examples, check out [the tests](test/).
113+
114+
## Features
115+
116+
### Retry on Failure
117+
118+
Automatically retry when intermittent failures occur. That is, when any of the retriable 5xx errors
119+
are returned from the API.
120+
121+
### Keys *and* Client IDs
122+
123+
Maps API for Work customers can use their [client ID and secret][clientid] to authenticate. Free
124+
customers can use their [API key][apikey], too.
125+
126+
## Building the Project
127+
128+
**Note:** You will need an API key or Client ID to run the tests.
129+
130+
# Generating documentation:
131+
$ sphinx-build -b html docs docs/html
132+
133+
# Installing dependencies:
134+
$ pip install requests responses
135+
136+
# Running tests:
11137
$ git submodule update --init
12138
$ python -m unittest discover
139+
140+
141+
[apikey]: https://developers.google.com/maps/faq#keysystem
142+
[clientid]: https://developers.google.com/maps/documentation/business/webservices/auth
143+
144+
[Google Maps API Web Services]: https://developers.google.com/maps/documentation/webservices/
145+
[Directions API]: https://developers.google.com/maps/documentation/directions
146+
[Distance Matrix API]: https://developers.google.com/maps/documentation/distancematrix
147+
[Elevation API]: https://developers.google.com/maps/documentation/elevation
148+
[Geocoding API]: https://developers.google.com/maps/documentation/geocoding
149+
[Time Zone API]: https://developers.google.com/maps/documentation/timezone
150+
151+
[issues]: https://github.com/googlemaps/google-maps-services-python/issues
152+
[contrib]: https://github.com/googlemaps/google-maps-services-python/blob/master/CONTRIB.md

0 commit comments

Comments
 (0)