From WeoGeo Support

Developer: API

Third Party Developer Documentation >> Developer: API

Introduction

The WeoGeo API is a beta release and is currently intended for our WeoGeo Library Administrators. The API is constantly evolving to accommodate the needs of its users and the increasing richness of the WeoGeo application. Please check this wiki page for up-to-date information about the API.

Basics

The WeoGeo API is implemented primarily as XML over HTTP and largely follows the REST principles. Resources are manipulated using the HTTP verbs GET/POST/PUT/DELETE (learn more about HTTP verbs here).

Basic HTTP Authentication is currently supported. Authentication is not maintained across requests. As such, your API key or your WeoGeo login credentials must be sent with every request. If you wish to use your API key, you can find it on your library settings page.

All the API documentation uses the API key in its calls. However, many applications, especially ones that are created for others to use, will need to use the username/password alternative. In this case, replace -u #{api_key}: with -u #{uname}:#{pwd} in the curl requests. Please note that an API key is offered since it remains static (versus #{uname}:#{pwd} which is subject to user's behavior) and hence offers an advantage when coding an application for your own use.

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. Setting the "Accept" header to "application/xml" to receive XML format is critical, because failure to do so will return HTML.

All requests on WeoGeo Library require usage of the API key. Example with curl (to know more about curl, please visit [1]):

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

JSON:
curl -u #{api_key}: -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. Error status codes can be found here.

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

Here is a breakdown of the curl request:

• #{} is Ruby notation for a variable. You can replace these with values.
• -u #{api_key} 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.
• Optionally, set the "Accept" header to "application/xml" to receive XML format in reply (defauts to HTML).
• #{hostname} is the URL of the WeoGeo Library or https://market.weogeo.com for WeoGeo Market. Note that when the API key (or user name/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). On WeoGeo Library, use http:// in the URL.
• #{token} is the unique identifier for a Listing or Job.

Important Notice Regarding Website Release 2.0.11:

After upgrading our webserver to Fedora 12 which uses openssl 1.0.0 beta 4, 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.

Case Studies

Examples showcasing usage of our APIs to address customer needs. See more here.