FTS Public Endpoints

This endpoint will return a list of flows categorised as incoming, internal or outgoing to a specified boundary. It will also include the totals of incoming and outgoing flows as separate properties and a count of the number of flows in the results.

This endpoint must be supplied with certain query parameters in order to retrieve a resultset. The query parameters are divided into 3 types:

  • Boundary parameters
  • Filter parameters
  • Grouping parameters

Boundary Parameters

Boundary parameters are used to draw an envelope around a set of flows. This will specify the flow records to be returned in the result set, as well as categorise the flows as incoming, internal or outgoing in relation to the boundary.

The valid boundary parameters to be used on this endpoint are based on the objects linked to flows. Note that although these objects are linked to a flow as either source or destination objects, when specifying a boundary, it is not required to specify the objects as a source or destination. It is only necessary to specify the object type and the value. The api will return all flows where the object appears either as a source or destination of the flow.

General usage

  • To specify a boundary simply add the parameter name with its value as a query parameter e.g. by organization abbreviation fts/flow?organizationAbbrev=wfp
  • To specify more than one value for the same parameter, use a comma e.g. fts/flow?organizationAbbrev=wfp,unicef
  • To specify combinations of objects, combine with an ampersand e.g. fts/flow?organizationAbbrev=wfp,unicef&year=2015

Note that the boundary parameters will get all flows where either the source or destination objects contain all the parameters specified. Values of the same object type will have an “OR” condition applied between them. Values of different object types will have an “AND” condition applied between them. For example:

/v1/public/fts/flow?organizationAbbrev=wfp,unicef&year=2015

will return all flows which match this condition:

((Source organization is WFP or UNICEF) and (source year is 2015))
or
((Destination organization is WFP or UNICEF) and (destination year is 2015))

The list of available object types and query parameter names are detailed below. To find lists of valid id’s or codes, refer to the list of reference data endpoints.

Organization object Parameter names:

  • organizationAbbrev - string
  • organizationId - integer

Full list of valid values can be found here.

Plan object Parameter names:

  • planId - integer
  • planCode - string

Full list of valid values can be found here.

Emergency object Parameter names:

  • emergencyId - integer
  • emergencyGlideId - string

Full list of valid values can be found here.

Year object Parameter names:

  • year - integer

Location object Parameter names:

  • locationId - integer
  • countryISO3 - string. The value can be one of the standard 3 letter iso codes for countries.

Sector object Parameter names:

  • globalclusterId - integer
  • globalClusterCode - string. This is a 3 letter code

Full list of valid values can be found here.

Project object Parameter names:

  • projectId - integer
  • projectCode - string

Field Cluster object Parameter names:

  • fieldClusterId - integer

Filter Parameters

Once a boundary has been set, you can reduce the result set with filter query parameters. Note the filters do not change the categorization (incoming, internal, outgoing) of a flow relative to the boundary.

The available filterBy parameters are the same set of object parameters as the boundary parameters, but with direction “source” or “destination” prepended to them. This allows the filtering of object values either as a source or a destination of a flow. For instance, if you wanted a list of all of the flows in the year 2015 boundary and wanted to filter that result set with flows which have a destination global cluster of Health, then you would set the parameters as such:

/v1/public/fts/flow?year=2015&filterBy=destinationGlobalClusterCode:HEA

If there are multiple filter options, you may add multiple “filterBy” parameters, one for each object direction and name. To specify more than one value for the same parameter, use a comma which will apply a OR condition between the filter values.

&filterBy=destinationGlobalClusterCode:HEA&filterBy=destinationLocationID:114,115

This will filter flows where destinationGlobalClusterCode is Health AND destinationLocationID is 114 OR 115.

The following is the list of valid filter by keys:

  • sourceOrganizationId
  • destinationOrganizationId
  • sourceOrganizationAbbrev
  • destinationOrganizationAbbrev
  • sourcePlanId
  • destinationPlanId
  • sourcePlanCode
  • destinationPlanCode
  • sourceEmergencyId
  • destinationEmergencyId
  • sourceEmergencyGlideId
  • destinationEmergencyGlideId
  • sourceYear
  • destinationYear
  • sourceLocationId
  • destinationLocationId
  • sourceCountryISO3
  • destinationCountryISO3
  • sourceGlobalClusterId
  • destinationGlobalClusterId
  • sourceGlobalClusterCode
  • destinationGlobalClusterCode
  • sourceProjectId
  • destinationProjectId
  • sourceProjectCode
  • destinationProjectCode
  • sourceOrganizationTypeId
  • destinationOrganizationTypeId

Grouping Parameters

Once a boundary has been specified, the result set returned can be grouped based on the source and destination objects each flow is linked to. Flows can only be grouped by one object type at a time, and the output will consist of 4 standard reports:

  1. Sum of incoming flows grouped by the specified source object type
  2. Sum of incoming flows grouped by the specified destination object type
  3. Sum of incoming and internal flows grouped by the specified destination object type of minus the sum outgoing and internal flows grouped by source objects
  4. Sum of outgoing flows grouped by destination objects

The parameter name is “groupby”. For example:

/v1/public/fts/flow?countryISO3=SDN&year=2015&groupby=organization.

This will return an output grouping the flows by organization for the country Sudan in the year 2015.

The valid values for the “groupby” parameter are:

  • Organization
  • OrganizationType
  • Country
  • Plan
  • Emergency
  • Project
  • GlobalCluster
  • Cluster
  • Year
  • ProjectPriority
  • ProjectSubsetOfPlan
  • ProjectCustomLocation
  • ProjectGenderMarker
  • ProjectResponseType

Format Options

The API supports both JSON and XML response formats. By default, all API responses are returned in JSON format. To return data in XML format, add “format=xml” as a parameter.

Example:

/v1/public/fts/flow?year=2016&format=xml
get

Retrieve a set of flows by boundary.

RPM Public Endpoints

get

Retrieve plans by country.

get

Retrieve a plan by ID.

get

Retrieve a plan by code.

get

Retrieve plans by year.

Global Cluster

get

Retrieve a list of all global clusters

Location

get

Retrieve a list of all locations

Organization

get

Retrieve a list of all organizations

Project

get

Retrieve a project by code.

get

Retrieve a project by ID.

get

Retrieve projects in a plan by plan ID.

get

Retrieve projects in a plan by plan code.

Emergency

get

Retrieve a emergency by ID.

get

Retrieve emergencies by year.

get

Retrieve emergencies by country.

Plan

get

Retrieve a plan by ID.

get

Retrieve a plan by code.

get

Retrieve plans by year.

get

Retrieve plans by country.