Home | Community | FAQ | Twitter

API documentation


API tools: Authentication, Data retrieval, Data push, Settings update

API handlers:

Authentication handler (oauth):

/oatuh/token.php: Authentication

Authentication based interface (pds):

/projects/API_VERSION/projectname/pds.php: Data retrieval, Data push, Settings update

Non authenticated requests (web):


PDS API version:

Example: http://openbiomaps.org/projects/dead_animals/v2.1/pds.php The default version setting (if the version string missing from the URL) is 1.1., which compatible with the 2.0 and backward compatible with the 1.0.


An oauth2 implementation based on ttps://bshaffer.github.io/oauth2-server-php-docs/. OAUTH used in the web interface and in the PDS as well.


grant_type: password username: a rergistered email address password: password string scope: list of requested scope access in the autenticated session access_token: a valid access token

html authentication of clients is nesessary

Available clients are mobile,R,web


OBM API interface. Created for R and mobile interface. It uses the OAUTH interface for authentication.


scope: data methods: see below

value: some scope uses it

header: (put data) JSON list of table columns’ names

ignore_warning: (put data) ignore upload warnings

form_id: (put_data) set form id

data: (put data) JSON array of upload data

GET type scopes

get_project_vars: query general project variables (available for non logined users as well).
Additional parameters:
project [text]: if not set default is the template project


  • project_url [url string]: web address of the project
  • login_url [url string]: login address of the project
  • game [on/off]: game available for android mobile app
  • public_mapserv [url string]: url of publicly accessible map service
  • rserver_port [numeric]: numeric port number of R-Shiny server, accessible on project_url
get_project_list: get list and basis info of database projects available on the server.
Additional parameters:

only-project [text]: query project parameters only for the selected project, default is to query all accessible projects accessible [text]: all/accessible. If accessible parameter given and its value is “accessible” (default)

  • If user already logined, get list of those projects where user has account and where there are public query/upload interfaces.
  • If the user not logined, query public projects only.


  • project_table [string],
  • creation_date [date string],
  • Creator [string],
  • email [string],
  • stage [string] experimental/testing/stable,
  • doi [string],
  • running_date [date string],
  • licence [string],
  • rum [string],
  • collection_dates [date range string],
  • subjects [text],

get_form_list: query the list of available upload forms,

get_form_data: query the fields of the selected form

Additional parameters: value [numeric] numeric id of a form.

Returns: see below.

get_profile: get profile data of a selected user

get_data: get data rows from a selected data table (observation data)

get_specieslist: get species list from a project

get_history: get history of a selected data row

get_report: perform a predefined query and get the result

get_tables: get list of tables in a project

POST type scopes

put_data: send/upload data using a selected form

PATCH type scopes

set_rules: update specific settings


Some kind of data access available on the web interface using stored unique URLs. These


query: (non-authenticated data retreive)

qtable: (non-authenicated table setting for data retreive)

report: (non-authenticated data retreive using stored query)

output: (non-authenticated data output setting)

LQ: (non-authenticated) display data from a stored query result

Form Data (get_form_data results) Explanations

Description: Optional column description Default value: Fix value for all observation. It can be controlled with some options.

  • ‘_input’ it works as any other field with sticky flag.
  • ‘_list’ it works as any other list type field with sticky flag.

in any other case the value can not be changed by the user users and the field can be hidden.

Column: The name of the column in the database

Short_name: Visible name of the column for the users

List: json array for menu items of a select menu. Can be {key:value} or [value,value] format

Control: Data checking commands: custom_check, minmax, spatial, nocheck, NULL

Count: (json array) If the control=’minmax’ this field contains the limit values, e.g 1:100

Type: column’s openbiomaps type:

  • autocomplete (json array)
  • boolen
  • crings (colour rings - text)
  • date (YYYY-MM-DD or other clear format)
  • datetime (YYYY-MM-DD HH:mm:ss)
  • file_id (file names as id by the server)
  • line (WKT geometry string)
  • list (json array)
  • numeric
  • point (WKT geometry string)
  • polygon (wkt geometry string)
  • text
  • time (HH:mm)
  • timetominutes (numeric value between 0 and 1440)
  • tinterval idő intervallum (HH:mm - HH:mm)
  • wkt (WKT sting)

Genlist: json array for menu items of an autocomplete menu. Can be {key:value} or [value,value] format Obl: 1,2,3 (non obligatory, obligatory, soft error) Soft error can be handled as non obligatory. Api_params: jason array of control values. Currently only ‘sticky’ Spatial_limit: WKT polygon string of spatial limit. It is used if the Control type is spatial.


curl \
-u mobile:123 http://openbiomaps.org/oauth/token.php \
-d “grant_type=password&username=foo@foobar.hu&password=abc123&scope=get_form_data+get_form_list+put_data
Data retrieval (form list):
curl \
-v http://openbiomaps.org/projects/checkitout/pds.php \
-d “access_token=d4fba6585303bba8da3e6afc1eb9d2399499ef3e&scope=get_form_list”
Result of a successful get_form_list call:
{“status”:”success”,”data”:[{“form_id”:”93”,”form_name”:”lepke űrlap”},{ …
Data retrieval (form fields):
curl \
-v http://openbiomaps.org/projects/checkitout/pds.php \
-d “access_token=d4fba6585303bba8da3e6afc1eb9d2399499ef3e&scope=get_form_data&value=93”
OR with central pds
curl \
-F ‘scope=get_form_data’ \
-F ‘value=93’ \
-F ‘project=checkitout’ \
OR with access token to retrieve data of a restricted form
curl \
-F ‘access_token=...’ \
-F ‘scope=get_form_data’ \
-F ‘value=124’ \
-F ‘project=checkitout’ \
Result of a successful get_form_data call:




{“description”:”faj neve”,”default_value”:null,”column”:”faj”,”short_name”:”faj”,”list”:””,”control”:”nocheck”,”count”:”{}”,”type”:”text”,”genlist”:null,”obl”:”1”,”api_params”:null},{... ]}

Data push:
curl \
-i \
-H “Content-Type:application/x-www-form-urlencoded” \
-H “Authorization:Bearer ...” \
-d “scope=put_data” \
-d “form_id=128” \
-d “header=[“obm_geometry”,”obm_datum”,”time”,”datum”,”comment”,”longitude”,”latitude”,”observer”]” \
-d “data=[{“obm_geometr y”:”point(48.071187 19.293714)”,”obm_datum”:”2018-04-03 23:05”,”time”:”12”,”datum”:”2018-04-03”,”comment”:”asdad”,”longitude”:”0”,”latitude”:”0”,”observer”:”sdsaada”}]” \
-d “ignore_warning=1” \
Data push with attached files:
curl \
-F “access_token=...” \
-F ‘scope=put_data’ \
-F ‘form_id=58’ \
-F ‘header=[“faj”,”obm_geometry”,”obm_files_id”]’ \
-F ‘batch=[\
{“data”:[{“faj”:”Sylvia curruca”,”obm_geometry”:”POINT(22.0 46.3)”}],”attached_files”:”file1,file2”},\
{“data”:[{“faj”:”Lanius Collurio”,”obm_geometry”:”POINT(21.5 47.1)”}],”attached_files”:”file3”}]’ \
-F 'file1=@file1‘ \
-F 'file2=@file2‘ \
-F 'file3=@file3‘ \
Data retrieval (non-authenticated report):
wget http://localhost/biomaps/projects/dinpi/?report=2@szamossag&output=csv
Refresh token (from R):

curl \
-F ‘grant_type=refresh_token’ \
-F ‘refresh_token=...’ \
-F ‘client_id=R’ \

“scope”:”get_form_data ...”,

Project list (using central pds):

curl \
-F ‘scope=get_project_list’ \

JSON array of those project which has public upload forms, or the user (if logined) member of it.

General API answers

Based on: https://labs.omniti.com/labs/jsend


X: success, error, fail