API Question: Correct use of facets/theme to filter a Job Search

[Maurice Bowen]

A question on the correct way to construct the URL when using facets (themes) with the API @ http://apidoc.rwlabs.org/#facet

Objective:

I'd like to limit a Job Search by Theme (agriculture) and Title (manager) using the API

Example:

Here is the search works normally ==> http://reliefweb.int/jobs?theme=4587&search=manager#content

Progress with the API Code

• Current API Code: ( as entered here ==> http://apidoc.rwlabs.org/#facet)
• http://api.reliefweb.int/v1/jobs?appname=apidoc&filter[field]=theme.name&filter[value]=Agriculture&filter[field]=title&filter[value]=manager&fields[include][]=theme
• ===>works partly but does not filter on Theme correctly

What am I doing wrong?

[Jonathan]

Dear Maurice,

Thank you for your interest in using the ReliefWeb API.

To filter on several fields at the same time (theme and title in that case), you need to use a "conditional" filter  (see http://apidoc.rwlabs.org/#filter" => "conditions" parameter and the "Reports tagged with France or Spain but not Italy" example).

Using a conditional filter, you can rewrite your query this way:

https://api.reliefweb.int/v1/jobs?appname=my-app&filter[operator]=and&filter[conditions][0][field]=theme.name&filter[conditions][0][value]=Agriculture&&filter[conditions][1][field]=title&filter[conditions][1][value]=manager&fields[include][]=theme

This can be read:

- Conditions:

  - 0: 

    - Field: theme

    - Value: Agriculture

  - 1:

    - Field: title

    - Value: manager

With the "and" operator, as you want to find documents which contain both Agriculture and manager.

Alternatively, you could filter only on theme Agriculture and use the full text search for "manager" (query parameter: http://apidoc.rwlabs.org/#query).

For example, to have the same results as http://reliefweb.int/jobs?theme=4587&search=manager, you would use the following query: 

https://api.reliefweb.int/v1/jobs?appname=my-app&filter[field]=theme.name&filter[value]=Agriculture&query[value]=manager&fields[include][]=theme

Also please note, that it is recommended to use the API over https: https://api.reliefweb.int/v1/jobs and you should use a unique name that identifies you application for the "appname" parameter.

Best regards,

Jonathan

[Maurice Bowen]

Thanks Jonathan,

I had used that exactly as you prescribed but noticed for example that with record 1916933 that multiple themes were returned, not just Agriculture.

Could it be that one job listing has multiple themes as in a one to many relationship?

Regards,
Maurice

[Jonathan]

The documentation is lacking on that point but yes, jobs can have several themes (up to 3). If you filter by theme=Agriculture, you will get all the jobs tagged with Agriculture but some of them may have other themes as well.

[Maurice Bowen]

Great discussion and I am now fully enlightened so thanks for all your prompt help - greatly appreciated!