Skip to content

Commit fd74e39

Browse files
ischneiderischneider
authored
Merge pull request #100 from planetlabs/v1
V1
2 parents fb9c913 + a6b24a3 commit fd74e39

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+3645
-2016
lines changed

‎.travis.yml

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,9 @@ python:
55
cache:
66
directories:
77
- $HOME/.cache/pip
8+
before_install:
9+
- pip install --upgrade pytest
810
install:
9-
- "pip install flake8"
10-
- "pip install -e .[dev]"
11-
before_script:
12-
- flake8 planet tests
11+
- pip install -e .[dev]
1312
script:
14-
- "py.test"
15-
13+
- make check html-docs

‎CHANGES.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
1.0.0 (2017-04-01) Code name: no-joke
2+
-------------------------------------
3+
- Remove V0 API support
4+
- Initial V1 Data API support
5+
16
0.0.6 (2016-02-17)
27
------------------
38
- Support for 'aoi_id' (saved geometry) queries in 'search' command.

‎Makefile

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,24 @@
11
GH_PAGES_SOURCES = planet docs Makefile
22

33
check:
4-
py.test tests
4+
py.test --doctest-modules planet tests
55
flake8 planet tests
66

7+
coverage:
8+
py.test --doctest-modules --cov planet --cov-report=html:htmlcov tests planet/api
9+
710
pex:
8-
pex . -o dist/planet -m planet.scripts:cli
11+
# disable-cache seemed required or the older version would be used
12+
pex . -o dist/planet -e planet.scripts:main --disable-cache
913

1014
html-docs:
1115
python docs/source/generate.py
1216
$(MAKE) -C docs clean html
1317

18+
auto-docs:
19+
which sphinx-autobuild || ( echo 'PLEASE INSTALL sphinx-autobuild: pip install sphinx-autobuild'; exit 1 )
20+
sphinx-autobuild --watch planet docs/source docs/build/html
21+
1422
docs-zip: html-docs
1523
cp -a docs/build/html planet-docs
1624
zip -m -r dist/planet-docs.zip planet-docs

‎README.rst

Lines changed: 30 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,47 @@
22
Planet API Client
33
=================
44

5-
**PRE-ALPHA SOFTWARE - MAY CHANGE**
6-
7-
Initial, incomplete, strawman effort at a Python client to Planet's public API.
5+
Python client library and CLI for Planet's public API.
86

97
.. image:: https://travis-ci.org/planetlabs/planet-client-python.svg?branch=master
108
:target: https://travis-ci.org/planetlabs/planet-client-python
119

1210

11+
Installation
12+
------------
13+
14+
Via pip::
15+
16+
pip install planet
17+
18+
A PEX executable (Windows not supported) and source releases are
19+
`here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
20+
21+
1322
Documentation
1423
-------------
1524

16-
`https://planetlabs.github.io/planet-client-python/index.html <https://planetlabs.github.io/planet-client-python/index.html>`__
25+
Online documentation: `https://planetlabs.github.io/planet-client-python/index.html <https://planetlabs.github.io/planet-client-python/index.html>`__
1726

27+
Documentation is also provided for download `here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
1828

19-
Installation
20-
------------
2129

22-
Executable CLI releases and documentation are `here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
30+
Development
31+
-----------
2332

2433
To develop with or use the library in your own projects, see the `wiki <https://github.com/planetlabs/planet-client-python/wiki>`__.
2534

2635

36+
API Key
37+
-------
38+
39+
The API requires an account for use. `Signup here <https://www.planet.com/explorer/?signup>`__.
40+
41+
This can be provided via the environment variable `PL_API_KEY` or the flag `-k` or `--api-key`.
42+
43+
Using `planet init` your account credentials (login/password) can be used to obtain the api key.
44+
45+
2746
Example CLI Usage
2847
-----------------
2948

@@ -35,25 +54,10 @@ Basics and help::
3554

3655
planet
3756

38-
OR specific command help::
39-
40-
planet search --help
41-
42-
An API key is `required <https://www.planet.com/explorers/>`__.
57+
The CLI provides access to the `data API <https://www.planet.com/docs/reference/data-api/>`__ ::
4358

44-
This can be provided via the environment variable `PL_API_KEY` or the flag `-k` or `--api-key`. Using the `planet init` the username and password can be used and saved instead.
59+
planet data
4560

46-
Examples
47-
~~~~~~~~
48-
49-
Get a visual ortho scene by id (writes to working directory)::
50-
51-
planet download 20150825_180952_1_0b07
52-
53-
Get scene metadata by id (and pretty print)::
54-
55-
planet metadata -pp 20150825_180952_1_0b07
56-
57-
Get a list of all mosaics::
61+
OR specific command help::
5862

59-
planet mosaics
63+
planet data download --help

‎docs/source/_static/custom.css

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
div.body, body {
2+
background-color: #f2f2f2;
3+
}
4+
5+
.documentwrapper {
6+
min-height: 80vh;
7+
}
8+
9+
pre {
10+
background-color: #191919;
11+
word-wrap: break-word;
12+
white-space: pre-wrap;
13+
}
14+
pre span {
15+
font-weight: 800;
16+
}
17+
18+
.highlight-text .highlight pre,
19+
.highlight-bash .highlight,
20+
.highlight-bash .highlight .m,
21+
.highlight-bash .highlight .s2,
22+
.highlight-python .highlight .n,
23+
.highlight-python .highlight .p,
24+
.highlight-default .highlight .n,
25+
.highlight-default .highlight .p
26+
{
27+
color: #f2f2f2;
28+
}
29+
30+
.highlight-bash .highlight .c1,
31+
.highlight-python .highlight .c1,
32+
.highlight-python .highlight .s1,
33+
.highlight-default .highlight .c1,
34+
.highlight-default .highlight .s1
35+
{
36+
color: #b5bd68;
37+
}
38+
39+
.highlight-python .highlight .k,
40+
.highlight-python .highlight .kn,
41+
.highlight-python .highlight .ow,
42+
.highlight-default .highlight .k,
43+
.highlight-default .highlight .kn,
44+
.highlight-default .highlight .ow,
45+
.highlight-default .highlight .go
46+
{
47+
color: #b294bb;
48+
}
49+
50+
.highlight-javascript .highlight .p
51+
{
52+
color: #f2f2f2;
53+
}

‎docs/source/_static/logo.png

-12.2 KB
Binary file not shown.

‎docs/source/_static/logo.svg

Lines changed: 1 addition & 0 deletions
Loading

‎docs/source/alabaster_planet.py

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1-
pblue = '#008fd5'
2-
sblue = '#18aae6'
3-
pgrey = ' #666666'
1+
pgrey = '#191919'
2+
pprimary_dark = '#006c72'
3+
44

55
html_theme_options = {
6-
'logo': 'logo.png',
7-
'body_text': '#000',
6+
'logo': 'logo.svg',
7+
'body_text': 'lighten(black, 20%)',
88
'gray_1': pgrey,
9-
'link': pblue,
10-
'sidebar_search_button': pblue,
11-
'sidebar_link': pblue,
9+
'link': pgrey,
10+
'font_family': 'Helvetica, sans-serif',
11+
'font_size': '14px',
12+
'sidebar_search_button': pprimary_dark,
13+
'sidebar_link': pprimary_dark,
1214
'github_button': 'false',
13-
}
15+
'fixed_sidebar': True,
16+
}

‎docs/source/api/examples.rst

Lines changed: 30 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Everything needed is provided in the `api` module.
88

99
.. code-block:: python
1010
11-
from planet import api
11+
from planet import api
1212
1313
Creating a Client
1414
-----------------
@@ -17,63 +17,39 @@ Without any arguments, the Client will look for an API_KEY using the operating s
1717

1818
.. code-block:: python
1919
20-
client = api.Client()
20+
client = api.ClientV1()
2121
22-
Searching for Scenes
23-
--------------------
22+
Searching for Items
23+
-------------------
2424

25-
Get the most recent Planet scenes.
25+
A common case is searching for items in an AOI.
2626

2727
.. code-block:: python
2828
29-
body = client.get_scenes_list(scene_type='ortho')
29+
aoi = {
30+
"type": "Polygon",
31+
"coordinates": [
32+
[
33+
[-122.54, 37.81],
34+
[-122.38, 37.84],
35+
[-122.35, 37.71],
36+
[-122.53, 37.70],
37+
[-122.54, 37.81]
38+
]
39+
]
40+
}
3041
31-
Get the most recent Landsat scenes.
42+
# build a filter for the AOI
43+
query = api.filters.and_filter(
44+
api.filters.geom_filter(aoi)
45+
)
46+
# we are requesting PlanetScope 4 Band imagery
47+
item_types = ['PSScene4Band']
48+
request = api.filters.build_search_request(query, item_types)
49+
# this will cause an exception if there are any API related errors
50+
results = client.quick_search(request)
3251
33-
.. code-block:: python
34-
35-
body = client.get_scenes_list(scene_type='landsat')
36-
37-
Providing metadata filters in a search.
38-
39-
.. code-block:: python
40-
41-
filters = { 'sat.id.eq' : '090b'}
42-
body = client.get_scenes_list(scene_type='landsat', **filters)
43-
44-
Using an AOI (in WKT in this example) to search.
45-
46-
.. code-block:: python
47-
48-
wkt = 'POINT(-100 40)'
49-
body = client.get_scenes_list(scene_type='landsat', intersects=wkt)
50-
51-
Handling a response `body` - the `get` method returns JSON (in this case, GeoJSON).
52-
53-
.. code-block:: python
54-
55-
geojson = body.get()
56-
# the results are paginated and the total result set count is provided
57-
print '%s total results' % geojson['count']
58-
# loop over features and print the scene 'id'
59-
for f in geojson['features']:
60-
print f['id']
61-
62-
Downloading Scenes
63-
------------------
64-
65-
One or more scenes may be downloaded using scenes ids. Downloading is currently
66-
done asynchronously and a callback must be provided. The callback will execute
67-
when data is available.
68-
69-
.. code-block:: python
70-
71-
scene_ids = ['20150810_235346_0b10', '20150810_235345_0b10']
72-
# create a callback that will write scenes to the 'downloads' directory
73-
# note - the directory must exist!
74-
callback = api.write_to_file('downloads')
75-
bodies = client.fetch_scene_geotiffs(ids, callback=callback)
76-
# await the completion of the asynchronous downloads, this is where
77-
# any exception handling should be performed
78-
for b in bodies:
79-
b.await()
52+
# items_iter returns an iterator over API response pages
53+
for item in results.items_iter():
54+
# each item is a GeoJSON feature
55+
sys.stdout.write('%s\n' % item['id'])

‎docs/source/api/index.rst

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,6 @@ API
33

44
Unless noted here, other classes, modules or functions should be considered 'private' and subject to change.
55

6-
.. warning::
7-
As this project is still in development, there may be reorganization and modifications that cause breaking changes.
8-
96
.. toctree::
107
:maxdepth: 3
118

0 commit comments

Comments
 (0)