Creating search URLs automatically

The data.fao.org Metadata/Data Query API Builder tool automatically generates APIs to help you to make search requests. It creates URLs dynamically and allows access to the diverse functionalities that are available in data.fao.org. The Metadata/Data Query API Builder can be found here.

To generate APIs automatically, perform the following steps:

  • fill in the fields according to the API that you want to generate
  • press execute button

To extract protected data from the system, the queries must be performed in secure mode. To do this, it is necessary to login to the FAOdata system through the Login button on the top of the page and, after this, check the Secure field on the form.

How to configure a search filter

As you chose and change the field values, the URL field changes according to your selection.

Examples:

Description: You can optionally choose an API example. By doing so the other fields will be automatically populated with the values corresponding to the example. You can then modify them to suite your needs. This field is optional.

Description:

No value required.

Secure:

Description: Allows you to perform queries in secure mode. This option allows the extraction of protected data in addition to the public ones.
Possible values: true, false

Language:

Description: Allows you to choose the human language in which you would like to see the results. This field is required.
Possible values: All, Arabic, Chinese, English (default), French, Russian, Spanish

API:

Description: Allows you to choose the type of API that you want to access. This field is optional.
Possible values:

Database:

Description: This field is required but only appears when you choose one of the APIs for which it is available, for example, 'find datasets by database'.
Possible values:

Dataset:

Description: This field is required but only appears when you choose one of the APIs for which it is available, for example, 'find measures by database, dataset'.
Possible values:

Dimension:

Description: This field is required but only appears when you choose one of the APIs for which it is available, for example, 'find hierarchies by database, dimension'.
Possible values:

Hierarchy:

Description: This field is required but only appears when you choose one of the APIs for which it is available, for example, 'find levels by database, dimension, hierarchy'.
Possible values:

Level:

Description: This field is required but only appears when you choose one of the APIs for which it is available, for example, 'find members by database, dimension, hierarchy, level'.
Possible values:

Format:

Description: Indicates the output format. This field is required.
Possible values: json, xml, txt, csv

Show Language:

Description: Indicates if the language has to be shown in the output. This field is optional.
Possible values: true, false

Page:

Description: Allows you to indicate the specific page of the results that you would like to see displayed. This field is optional.

Example: 5

Page size:

Description: Allows you to indicates the number of pages in which the results will display. This field is optional.

Example: 100

Full-text search:

Description: Allows you to indicates keywords. This can be used as a general filter. This field is optional and is not enabled for the 'find facts' Query API.

Example: crop

Filter clause:

Description: Allows you to filter search results. This is a structured search filter. This field is optional. When used for the 'find facts' Query API:

  • mandatory: at least one dimension; if it's a 'Time' dimension you do not need to specify the property
  • you can use the logical operator 'and' or 'eq' to build your clause

Syntax: Expr = Variable Op [Expr, Literal]

Possible values:

Filter clauseMeaningFilter clauseMeaningFilter clauseMeaning
!not>gte(greater than or equal)
!=not equal>=in(range)
&&and[lt(lower than)
(\"(double quote)lte(lower than or equal)
)\'(single quote)neq(not equal)
,]not
.andor
<eqtrue
<=false||(or)
=gt(greater than)

Example: urn eq "mais"

Field list:

Description: Indicates the result format. This field is optional. When used for the 'find facts' Query API:

  • each dataset’s dimension must be specified at least once, each one can be mentioned more than once if more than one property
  • at least one measure must be specified

Syntax: fieldName [AS alias]

Possible values: AS, as

Example: urn, mnemonic as name

Sort order:

Description: Indicates the order in which you want to see the results. This field is optional.

Syntax: field_Name value where value indicates the order in which you want to see the results display, either ascending or descending. The value is not case sensitive.

Possible values: ASC, DESC, asc, desc

Example: mnemonic ASC

Dynamic path parameters:

For specific queries, it is possible to indicate specific values for your search to be performed, such as:

  • Database: i.e. 'faostat'
  • Dataset: i.e. 'bal-crop'
  • Dimension: i.e. 'cnt'
  • Hierarchy: i.e. 'cnt'
  • Level: i.e. 'cnt'

This fields are required, but only appear when you choose one of the APIs for which they are available. For example, 'find properties by database, dataset, dimension, hierarchy, level'.