WeoGeo API Documentation

Documentation Conventions

Variables or other locations for user-specific data in provided examples will be wrapped with: #{}. For example "#{dataset_token}" would indicate the place in a string where a dataset token should be substituted. In instances where it is not obvious what this variable name references, a specific description will be provided.

Basics

Format-Specific Conventions

Although both the XML and JSON expressions of the API carry the same data, they do so in slightly different ways.

The JSON format, in keeping with the conventions of that file type, uses underscores to separate words within a tag name. (Example: data_created_on)

The XML format uses hyphens to separate words within a tag name. (Example: data-created-on) Lists are represented as one or more tags containing singular instances of a piece of data wrapped in a tag bearing their pluralized name.

<datasets>
  <dataset>...</dataset>
  <dataset>...</dataset>
</datasets>

Empty lists are represented by the containing element having no child elements.

<datasets>
</datasets>

REST Principles

The WeoGeo API is implemented primarily as XML over HTTP and largely follows the REST principles. In brief this means that, unless impossible or exceptionally inconvenient, the HTTP protocol will be used as a basic mechanism for categorizing requests and responses. You will likely want to have the definitions of HTTP status codes handy.

Resources are manipulated using the HTTP verbs GET/POST/PUT/DELETE. In many cases these are used to retrieve, create, update, and delete resources, respectively. Additionally, some behaviors will use PUT to invoke a very specific action (e.g. ordering a job) on a resource.

Resource representations will include relevant URLs to take further actions with that resource. For instance, the representation of a job will include the URL used to access the downloads api needed to retrieve files. This is functionally similar to links in html documents: resources that are available and relevant to an api request will have their URLs exposed as named values.

Due to our mechanism for referring to URLs by name, it is possible that the URLs associated with an action may change. API clients should not cache URLs retrieved in documents for more than 24 hours to ensure that the their URLs are still valid.

Authentication

Basic HTTP Authentication is currently supported. Authentication is not maintained across requests at this time.


NOTE: It is possible to access some APIs via unsecured http connections. Be careful not to send your username/password with these requests, as that will expose them in an unencrypted form.


Response Format

The API calls can be executed to return either XML or JSON responses. So, be sure to set the "Content-Type" header in your requests to "application/xml" or "application/json", which will identify the format of the data being requested.

In most cases, the content of xml and json responses are the same. Differences will be noted when they are present. In general, XML responses will use hyphens between multiple words, while JSON responses use underscores.

The API Document

Rather than requiring that clients know how to construct API URLs, our system embeds those URLs in relevant resources. The starting point for all API clients is the API document, which is a pre-defined location where an initial set of resource URLs is hosted. This document is designed to be versioned along with the API, if and when versioning becomes necessary. Clients should request the file at https://#{hostname}.weogeo.com/api/#{version}.#{format} where hostname is the subdomain of the private store or Market you are interacting with, version is the version of the API that your client is requesting (currently 1.0.0) and format is the document format requested (either XML or JSON). This document can be cached during an individual usage session, but probably should not be cached for longer than 24 hours.

URL Templates

In many cases you will already have the unique identifier for a resource that you want to interact with. Rather than forcing you to retrieve the relevant document for that resource, the API provides url templates that can be used to construct URLs for interacting with the resource. These always include ${id} in the URL. Client programs should programmatically replace that text with the relevant identifier.

Example:

# This url can be used to display a dataset, where the id is either the dataset's token or its permalink.
http://market.weogeo.com/datasets/${id}.html

Curl

Most of the examples in this documentation are written so they can be executed with curl. If you are not familiar with it, you can (learn more about curl here).

Here is a brief walkthrough of one of our documentation examples:

XML:

curl -u #{uname}:#{pwd} -H 'Content-Type: application/xml' http://#{hostname}/datasets/#{token}.weo    

JSON:

curl -u #{uname}:#{pwd} -H 'Content-Type: application/json' http://#{hostname}/datasets/#{token}.json

The request above will return an XML-formatted or JSON-formatted response if successful and a 200 status code. In case of request failure, appropriate error information is returned with the HTTP status code.

Note: For sake of brevity and clarity, we only use XML API requests in our documentation.

Here is a breakdown of the curl request:

  • -u #{uname}:#{pwd} specifies the User requesting the data.
  • Set the "Content-Type" header (-H) in your requests to “application/xml”, which will identify the format of the data being sent.
  • You may need to directly set the "Accept" header to "application/xml" to receive XML format in replies.
  • #{hostname} is the URL of a private store or https://market.weogeo.com for WeoGeo Market. Note that when username and password is used for curl requests to WeoGeo Market, the network security protocol HTTPS must be used (i.e. the request should have https:// in the URL and your curl utility will need to be compiled with SSL libraries).
  • #{token} is the unique identifier for a Listing or Job.

Important Notice Regarding Curl and SSL:

Certain curl clients can no longer complete the ssl handshake. Forcing curl to use v3 solves it in all cases we have seen (providing the -3 flag to command line curl, or CURLOPT_SSLVERSION=CURL_SSLVERSION_SSLv3 to libcurl). Has been submitted upstream to be resolved. See http://curl.haxx.se/mail/archive-2010-03/0069.html for more information. Our curl examples will use -3 flag.