Consumers¶

Preparing URLs¶

1. Use this documentation and the browse-able API to determine the URL that represents the resource to add, e.g. /api/observations/?genus=puma. This URL is not quite ready, a couple more things have to be done since this will only return the first 10 records in a format many applications, e.g. QGIS, cannot yet digest.
2. Add the page_size parameter to get more results. If you open the URL below you will get a count of returned records, for the puma example its ~ 260 (which changes as new data sets come available). For smaller numbers of records (up to ~ 1000) you can just increase the page_size accordingly. /api/observations/?genus=puma&page_size=262.
3. For larger returns you might need to send several requests using the page parameter. E.g. /api/observations/?genus=puma&page_size=100&page=1 and /api/observations/?genus=puma&page_size=100&page=2 etc.
4. Next you need to pick the correct return format by adding the format parameter. Using the example from 2 above, it would be /api/observations/?genus=puma&page_size=262&format=geojson.
5. Modify the field selection parameters (fields, exclude, extra) to get additional data, or to reduce the amount of data returned by the API.

Microsoft Excel, LibreOffice Calc, and Similar¶

If you request ?format=csv the API will return a CSV file that will be – depending on your system – most likely trigger a download window to open. Such a comma-delimited CSV file can be opened within most spreadsheet applications. In many cases this will be as easy as choosing the ‘Open with ...’ option in the download menu.

A special case – preparing data for MaxEnt¶

Coming soon.

QGIS¶

QGIS is a very powerful alternative to ArcGIS and provides a powerful GIS desktop framework. GeoJSON data streams (from the Ecoengine) can be easily added as layers. Here is a short example how to add all occurrences of puma to your map using QGIS 2.0.1.

The following steps start from the URL generated above (https://ecoengine.berkeley.edu/api/observations/?genus=puma&page_size=262&format=geojson&georeferenced=True):

1. Open the “Add Vector Layer” dialogue

2. Select ‘Protocol’ of type ‘GeoJSON’, copy URL, and click open:

3. The result will be similar to this:

ArcGIS¶

The challenge for users of ArcGIS is that there is no GeoJSON import filter implemented if the data interoperability extension is not installed and paid for. However, there are a few ways to import the data below.

Quick and Dirty

The quickest “one off” fix is to download the data in CSV format e.g. /api/observations/?genus=puma&page_size=262&format=csv. The resulting CSV will contain the x and y coordinates in two fields geojson.coordinates.0 and geojson.coordinates.1, which need to be assigned while importing the CSV file in ArcMap.

Additionally, manually set the geographic reference system with the ‘Define Projection’ tool (which is DIFFERENT from the Project tool). Set to WGS84 if not requested otherwise.

See also http://support.esri.com/en/knowledgebase/techarticles/detail/27589.

More Elegant, Still Without Data Interoperability Extension

A second strategy – especially suitable for projects that work with scripts – is to use Pythons JSON and urllib2 libraries to map the API fields into an ArcMap feature class. The following code example can be used as a starting point to expand on.

The following code can be run in a ArcMap Python console (swap out output path). It will add the layer to the map.

import json
import urllib2
import arcpy

# Set up environment.
arcpy.env.outputCoordinateSystem = arcpy.SpatialReference(4326)
arcpy.env.overwriteOutput = True
arcpy.env.workspace = 'C:/pathtoworkspace'

# Make the API request.
response = urllib2.urlopen(
    'https://ecoengine.berkeley.edu/api/observations/'
    '?genus=lynx&format=geojson&georeferenced=True&page_size=100')

# Create a feature class from the response.
data = json.load(response)
points = [arcpy.AsShape(feature['geometry'], False)
          for feature in data['features']]
arcpy.CopyFeatures_management(points, 'lynx.shp')

Using data interoperability extension

Coming soon.

CartoDB¶

CartoDB is a web service that allows for the fast generation of maps from uploaded data. In addition, it will provide a RESTful API which wraps spatial SQL queries on the data. Users are allowed up to five public tables, 5Mbytes of storage, and 10000 monthly map views within a free account to evaluate the utility of CartoDB. For additional functionality you need to subscribe to one of their payment plans.

Steps to get Ecoengine data into a CartoDB table

1. Create an account and log in.
2. Go to “Your Dashboard”. Link will be on top of page.
3. If it is your first table, there will be a guide to create a table. Otherwise you will find an “New Table” link.
4. In both cases you will get to a window like below. Add your URL in the form field. In the example it is https://ecoengine.berkeley.edu/api/observations/?genus=lynx&format=geojson&page_size=700

5. After creating the table you can see your data instantly on a map by clicking the “Map View” tab.