The CloudBirders API
CloudBirders provides an API to allow third parties to upload birding trip reports via a direct integration. This can for example be used by bird observation sites to provide a trip report publication service towards CloudBirders.
The API basically allows you to submit a new trip report to Cloudbirders using a computer interface, rather than by manually filling out the Submit page. It supports the same input fields as the user form:
- title (short and meaningful description of the trip)
- a list of visited areas (area names must match the names used on the site)
- author (main author of the report - preferably 1 person)
- from & to (begin and end month/year of the trip)
- language (must be a language supported by Cloudbirders as listed in the WSDL - let us know if you want one added)
- travel mode (ind=independent,lta=local travel agent,btc=bird tour company)
- checklist type (al=annotated list,bl=basic list,nl=no list)
- has pictures (true or false)
- has GPS (true or false)
- has checklists of other taxa, rather than just birds (true or false)
- sharing under CC license allowed (true or false)
- number of days
- number of birds observed
- list of external links (URLs)
- list of attachments (with corresponding PDF trip reports attached to the SOAP request)
Trip reports will be reviewed by the CloudBirders administrators, similar to how the manual upload flow is reviewed today, before being publicly visible on the site.
The API is based on SOAP over https.
The WSDL is available here, and message definitions are here.
A set of sample requests is available in a SoapUI project file here.
Before you can get started, drop us an e-mail at firstname.lastname@example.org so we can provide you with a username and password that has API access.
The best place to start from is to look at the sample requests in the aforementioned SoapUI project. Pay close attention to the following:
- Authentication is based on WSS, so you need to put your username and password in the appropriate header.
As an example of how this is done, in SoapUI this is achieved as follows: go to Project => Show Project View => WS-Security Configurations => Outgoing WS-Security Configurations => "outgoing" => set your username and password there.
In your SOAP client of choice, you will have to setup a similar (equivalent) configuration.
- SOAP requests need to be explicitly configured to use this outgoing WSS configuration.
In SoapUI: in the request editor, click the "Auth" tab and select "Basic" authorization, then select "outgoing" as the "Outgoing WSS"
- Attachments are sent using MTOM.
In SoapUI: make sure that the "Enable MTOM" property of the request is set to "true".
To add or update an attachment, open the request editor and click the "Attachments" tab.
Make sure that the "Name", "Content type", "Part" and "ContentID" properties of the attachment match the "fileName", "contentType", and "binaryData" values (respectively) as in the provided examples. Note that only PDF attachments are allowed.
What to upload
An interesting trip report will typically contain detailed information on logistics, sites, guides, itinerary, travel arrangements, tips on how to find birds, etc etc.
On the other hand, a basic list of observations without any additional useful information will probably be of little interest to the average CloudBirders user.
We recommend to avoid uploading trip reports that offer limited added value to the travelling birder.
Don't hesitate to reach out to us at email@example.com if you have any questions or if you are having technical difficulties.