earth-genome / water-service

API for surface water from satellite imagery
http://earthgenome.org
7 stars 4 forks source link
Table of Contents

=========

Earth Genome

The Earth Genome is a 501(c)(3) nonprofit organization that provisions environmental information via web service APIs and custom decision support tools. Earth Genome’s initial tool is called the Green Infrastructure Support Tool, which values wetland restoration in financial terms based on water storage potential for industrial applications. The initial set of APIs include global surface water extent, California aquifer recharge potential, US crop composition, global deforestation, among others. The surface water API has been submitted as part of this RFP. The Earth Genome is run by the following experts:

The objective of the Earth Genome is to identify environmental web services that people will actually use for operational decisions. We work with teams across sectors, including the Dow Chemical Company, the World Resources Institute, and Microsoft to build tools and services that scale. We take our cues from 18F and the broader digital service community, ensuring that all we do abides by best practice standards of digital delivery.

water-service

The objective of this repository is to provision global data on surface water from Landsat 7 satellite imagery. This project represents a layer on top of Earth Engine, operationalizing remote sensing science for web app developers.

extent

This endpoint provides the extent of surface water for a supplied area and a supplied year (1999-2014) as a GeoJSON polygon.

Base URL

http://water-test.appspot.com/water/poly

parameter type default format description
geometry list n/a [[lat, lon], [lat, lon], ...] list of lat-lon tuples defining the are of interest
date int n/a YYYY-01-01 year (the first of the year)
Example URL

http://water-test.appspot.com/water/poly?coords=[[-119.93,39.33],[-119.93,39.35],[-119.90,39.35],[-119.90,39.33],[-119.93,39.33]]&year=2014

{
    "date": "1999-01-01",
    "result": {
        "type": "FeatureCollection",
        "features": [
            {
                "geometry": {
                    "type": "Polygon",
                    "geodesic": false,
                    "coordinates": [
                        [
                            [
                                96.14937980516474,
                                16.70507102348662
                            ],
                            [
                                96.15027812044887,
                                16.70507102348662
                            ],
                            [
                                96.15027812044887,
                                16.705969338770743
                            ],
                            [
                                96.14937980516474,
                                16.705969338770743
                            ],
                            [
                                96.14937980516474,
                                16.70507102348662
                            ]
                        ]
                    ]
                },
                "type": "Feature",
                "id": "+107033+18596",
                "properties": {
                    "count": 1,
                    "label": 1
                }
            }
            "..."
        ]
    }
}

series

This endpoint provides the propotion of the supplied area that is covered by water for each available image within the supplied date range.

Base URL

http://water-test.appspot.com/water/series

parameter type default format description
geometry list n/a [[lat, lon], [lat, lon], ...] list of lat-lon tuples defining the are of interest
begin date n/a YYYY-MM-DD begin date
end date today YYYY-MM-DD end date
Example URL

http://water-test.appspot.com/water/series?coords=[[-119.93,39.33],[-119.93,39.35],[-119.90,39.35],[-119.90,39.33],[-119.93,39.33]]&begin=2010-02-02&end=2011-02-02

{
    "count": 12,
    "begin": "2010-02-02",
    "end": "2011-02-02",
    "result": [
        {
            "date": "2010-02-02",
            "area": 0.546627708789871
        },
        {
            "date": "2010-03-06",
            "area": 0.9044314584855125
        },
        "..."
        {
            "date": "2011-01-01",
            "area": 0.9385196006817629
        }
    ]
}

Using the API: example web application

A very simple web app that displays the data allows the user to draw a bounding box. The returned geometry is overlaid on the basemap, along with the water series as a D3 plot. The displayed water body is Washoe Lake, just north of Carson City, Nevada. Washoe Lake has "dried up a number of times since 1977," according to an article from a local news organization. When and how much? The web app allows users to watch the lake cycles and annual average extent of the lake. You can watch the change.

Screenshot

Development

The API runs on the Google App Engine Python SDK, which includes a web server application you can run on your computer that "simulates your application running in the App Engine Python runtime environment." To run locally, you will first have to contact @danhammer for credentials to access the backend. Once you have these credentials, you need only run the development server and check that it runs:

  1. Run dev_appserver.py --port=8080 . in the console from within the water-service directory.
  2. Navigate to localhost:8080 and you should see a success json object.

Once changes are made, submit a pull request to this repository and @danhammer