RSQ API API Reference

RSQ API is a full stack RESTful API allowing endpoints for entity lists, single entity access and complex query built requests. It’s a public API meaning there is no user authentication in place. API is versioned.

API Endpoint
http://api.unhcr.org/rsq/v1
Response Content-Types: application/json
Schemes: http
Version: 1.0.0

Categories and regions

Categories and regions

GET /categories

http://api.unhcr.org/rsq/v1/categories

Returns a list of codes and names :of categories for UNHCR resettlement submissions.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
Category

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "LPN",
    "name": "Legal and/or Physical Protection Needs"
  }
]
Categories and regions

GET /regions

http://api.unhcr.org/rsq/v1/regions

Returns a list of names of regions used by UNHCR to group Countries of Asylum.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
Region

Valid request

default

Unxpected error occured

Response Example (200 OK) 
[
  {
    "name": "Middle East and North Africa"
  }
]

Years

Years

GET /years

http://api.unhcr.org/rsq/v1/years

Returns a list of years for which there is available data on resettlement submissions and resettlement departures.

200 OK

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  2013,
  2014,
  2015,
  2016,
  2017
]
Years

GET /years/demographics

http://api.unhcr.org/rsq/v1/years/demographics

Returns a list of years for which there is available data on resettlement submissions demographics.

200 OK

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  2013,
  2014,
  2015,
  2016,
  2017
]

Countries

Countries

GET /asylums

http://api.unhcr.org/rsq/v1/asylums

Returns a list of available countries of asylum.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
CountryOfAsylum

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "HRV",
    "name": "Croatia",
    "region": "Europe"
  }
]
Countries

GET /origins/submissions

http://api.unhcr.org/rsq/v1/origins/submissions

Returns a list of available countries of origin for resettlement submissions data.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
CountryOfOrigin

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "HRV",
    "name": "Croatia",
    "region": "Europe"
  }
]
Countries

GET /origins/departures

http://api.unhcr.org/rsq/v1/origins/departures

Returns a list of available countries of origin for resettlement departures data.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
CountryOfOrigin

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "HRV",
    "name": "Croatia",
    "region": "Europe"
  }
]
Countries

GET /origins/demographics

http://api.unhcr.org/rsq/v1/origins/demographics

Returns a list of available countries of origin for resettlement submissions demographics data.

200 OK
CountryOfOrigin

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "HRV",
    "name": "Croatia",
    "region": "Europe"
  }
]
Countries

GET /destinations

http://api.unhcr.org/rsq/v1/destinations

Returns a list of available countries of resettlement.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
CountryOfResettlement

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "code": "HRV",
    "name": "Croatia",
    "region": "Europe"
  }
]

Helper

Helper

GET /fetchUrl

http://api.unhcr.org/rsq/v1/fetchUrl?urlHash=%2336Aq

Returns a full URL for existing URL hash. Hash sign has to be converted to HTML entity.

urlHash

# followed by a combination of 4 letters and/or numbers designating a unique query string

type
string
in
query
language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
200 OK
UrlFetch

Valid request

default

Unexpected error occured

Response Example (200 OK) 
[
  {
    "status": "success",
    "url": "http://api.unhcr.org/rsq/v1/submissions?asylum=&asylumCompare=&asylumRegion=&origin=AFG%2CBTN%2CCOD%2CERI%2CIRN%2CIRQ%2CMMR%2CSOM%2CSDN%2CSYR&originCompare=true&resettlement=&type=submissions&year=2013%2C2014%2C2015%2C2016%2C2017"
  }
]
Helper

GET /export/csv

http://api.unhcr.org/rsq/v1/export/csv?type=submissions&year=2017&origin=MMR%2CSYR&resettlement=NOR%2CUSA

Returns queried data in CSV format

200 OK

Valid request

default

Unexpected error occured

Response Example (200 OK) 
"file"

Query

Query

GET /submissions

http://api.unhcr.org/rsq/v1/submissions?page=1&year=2016%2C2017&origin=MMR%2CSYR&asylum=JOR%2CLBN&resettlement=NOR%2CUSA

Returns paginated resettlement submissions data for specific parameters. Returns 20 results per page.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
page

Current page of results

type
integer
in
query
year

One or more available years

type
integer[]
in
query
origin

One or more country of origin codes

type
string[]
in
query
originCompare

Used in combination with atleast one origin. Groups all other origins as "All others" entry in results

type
boolean
in
query
asylum

One or more country of asylum codes

type
string[]
in
query
asylumCompare

Used in combination with atleast one asylum. Groups all other asylums as "All others" entry in results

type
boolean
in
query
resettlement

One or more country of resettlement codes

type
string[]
in
query
yearSort

Sort results by year ascending or descending

type
string asc, desc
in
query
originSort

Sort results by country of origin ascending or descending

type
string asc, desc
in
query
asylumSort

Sort results by country of asylum ascending or descending

type
string asc, desc
in
query
resettlementSort

Sort results by country of resettlement ascending or descending

type
string asc, desc
in
query
personsSort

Sort results by number of persons ascending or descending

type
string asc, desc
in
query
200 OK
SubmissionsResponse

Valid request

default

Unexpected error occured

Response Example (200 OK) 
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "asylum": "JOR",
      "asylum_name": "Jordan",
      "destination": "NOR",
      "destination_name": "Norway",
      "persons": 14
    }
  ],
  "total": 12345,
  "url": "#c3X3",
  "page": 1,
  "totalPages": 10,
  "chartFilterTypes": {
    "origin": "boolean",
    "asylum": "boolean",
    "resettlement": "boolean"
  }
}
Query

GET /departures

http://api.unhcr.org/rsq/v1/departures?page=1&year=2016%2C2017&origin=MMR%2CSYR&asylum=JOR%2CLBN&resettlement=NOR%2CUSA

Returns paginated resettlement departures data for specific parameters. Returns 20 results per page.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
page

Current page of results

type
integer
in
query
year

One or more available years

type
integer[]
in
query
origin

One or more country of origin codes

type
string[]
in
query
originCompare

Used in combination with atleast one origin. Groups all other origins as "All others" entry in results

type
boolean
in
query
asylum

One or more country of asylum codes

type
string[]
in
query
asylumCompare

Used in combination with atleast one asylum. Groups all other asylums as "All others" entry in results

type
boolean
in
query
resettlement

One or more country of resettlement codes

type
string[]
in
query
yearSort

Sort results by year ascending or descending

type
string asc, desc
in
query
originSort

Sort results by country of origin ascending or descending

type
string asc, desc
in
query
asylumSort

Sort results by country of asylum ascending or descending

type
string asc, desc
in
query
resettlementSort

Sort results by country of resettlement ascending or descending

type
string asc, desc
in
query
personsSort

Sort results by number of persons ascending or descending

type
string asc, desc
in
query
200 OK
DeparturesResponse

Valid request

default

Unexpected error occured

Response Example (200 OK) 
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "asylum": "JOR",
      "asylum_name": "Jordan",
      "destination": "NOR",
      "destination_name": "Norway",
      "persons": 14
    }
  ],
  "total": 12345,
  "url": "#c3X3",
  "page": 1,
  "totalPages": 10,
  "chartFilterTypes": {
    "origin": "boolean",
    "asylum": "boolean",
    "resettlement": "boolean"
  }
}
Query

GET /demographics

http://api.unhcr.org/rsq/v1/demographics?page=1&year=2017&origin=MMR%2CSYR&resettlement=NOR%2CUSA

Returns resettlement submissions demographics data for specific parameters.

language

Return results will be translated in requested language. Defaults to english

type
string en, fr
in
query
year

One or more available years

type
integer[]
in
query
origin

One or more country of origin codes

type
string[]
in
query
originCompare

Used in combination with atleast one origin. Groups all other origins as "All others" entry in results

type
boolean
in
query
resettlement

One or more country of resettlement codes

type
string[]
in
query
200 OK
DemographicsResponse

Valid request

default

Unexpected error occured

Response Example (200 OK) 
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "destination": "NOR",
      "destination_name": "Norway",
      "femalesUnderage": 25,
      "femalesAdult": 300,
      "femalesSenior": 45,
      "femalesUnknown": 5,
      "femalesTotal": 375,
      "malesUnderage": 25,
      "malesAdult": 300,
      "malesSenior": 45,
      "malesUnknown": 5,
      "malesTotal": 375,
      "other": 5,
      "total": 755
    }
  ],
  "url": "#c3X3"
}

Schema Definitions

Category:

code: string
name: string
Example
{
  "code": "LPN",
  "name": "Legal and/or Physical Protection Needs"
}

Region:

name: string
Example
{
  "name": "Middle East and North Africa"
}

CountryOfAsylum:

code: string
name: string
region: string
Example
{
  "code": "HRV",
  "name": "Croatia",
  "region": "Europe"
}

CountryOfOrigin:

code: string
name: string
region: string
Example
{
  "code": "HRV",
  "name": "Croatia",
  "region": "Europe"
}

CountryOfResettlement:

code: string
name: string
region: string
Example
{
  "code": "HRV",
  "name": "Croatia",
  "region": "Europe"
}

UrlFetch:

status: string success, invalid
url: string
Example
{
  "status": "success",
  "url": "http://api.unhcr.org/rsq/v1/submissions?asylum=&asylumCompare=&asylumRegion=&origin=AFG%2CBTN%2CCOD%2CERI%2CIRN%2CIRQ%2CMMR%2CSOM%2CSDN%2CSYR&originCompare=true&resettlement=&type=submissions&year=2013%2C2014%2C2015%2C2016%2C2017"
}

ChartFilterTypes:

origin: boolean
asylum: boolean
resettlement: boolean
Example
{
  "origin": "boolean",
  "asylum": "boolean",
  "resettlement": "boolean"
}

SubmissionsResponse:

results: Submissions
total: integer
url: string
page: integer
totalPages: integer
chartFilterTypes: ChartFilterTypes
Example
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "asylum": "JOR",
      "asylum_name": "Jordan",
      "destination": "NOR",
      "destination_name": "Norway",
      "persons": 14
    }
  ],
  "total": 12345,
  "url": "#c3X3",
  "page": 1,
  "totalPages": 10,
  "chartFilterTypes": {
    "origin": "boolean",
    "asylum": "boolean",
    "resettlement": "boolean"
  }
}

Submissions:

year: integer
origin: string
origin_name: string
asylum: string
asylum_name: string
destination: string
destination_name: string
persons: integer
Example
{
  "year": 2013,
  "origin": "SYR",
  "origin_name": "Syrian Arab Rep.",
  "asylum": "JOR",
  "asylum_name": "Jordan",
  "destination": "NOR",
  "destination_name": "Norway",
  "persons": 14
}

DeparturesResponse:

results: Departures
total: integer
url: string
page: integer
totalPages: integer
chartFilterTypes: ChartFilterTypes
Example
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "asylum": "JOR",
      "asylum_name": "Jordan",
      "destination": "NOR",
      "destination_name": "Norway",
      "persons": 14
    }
  ],
  "total": 12345,
  "url": "#c3X3",
  "page": 1,
  "totalPages": 10,
  "chartFilterTypes": {
    "origin": "boolean",
    "asylum": "boolean",
    "resettlement": "boolean"
  }
}

Departures:

year: integer
origin: string
origin_name: string
asylum: string
asylum_name: string
destination: string
destination_name: string
persons: integer
Example
{
  "year": 2013,
  "origin": "SYR",
  "origin_name": "Syrian Arab Rep.",
  "asylum": "JOR",
  "asylum_name": "Jordan",
  "destination": "NOR",
  "destination_name": "Norway",
  "persons": 14
}

DemographicsResponse:

results: Demographics
url: string
Example
{
  "results": [
    {
      "year": 2013,
      "origin": "SYR",
      "origin_name": "Syrian Arab Rep.",
      "destination": "NOR",
      "destination_name": "Norway",
      "femalesUnderage": 25,
      "femalesAdult": 300,
      "femalesSenior": 45,
      "femalesUnknown": 5,
      "femalesTotal": 375,
      "malesUnderage": 25,
      "malesAdult": 300,
      "malesSenior": 45,
      "malesUnknown": 5,
      "malesTotal": 375,
      "other": 5,
      "total": 755
    }
  ],
  "url": "#c3X3"
}

Demographics:

year: integer
origin: string
origin_name: string
destination: string
destination_name: string
femalesUnderage: integer
femalesAdult: integer
femalesSenior: integer
femalesUnknown: integer
femalesTotal: integer
malesUnderage: integer
malesAdult: integer
malesSenior: integer
malesUnknown: integer
malesTotal: integer
other: integer
total: integer
Example
{
  "year": 2013,
  "origin": "SYR",
  "origin_name": "Syrian Arab Rep.",
  "destination": "NOR",
  "destination_name": "Norway",
  "femalesUnderage": 25,
  "femalesAdult": 300,
  "femalesSenior": 45,
  "femalesUnknown": 5,
  "femalesTotal": 375,
  "malesUnderage": 25,
  "malesAdult": 300,
  "malesSenior": 45,
  "malesUnknown": 5,
  "malesTotal": 375,
  "other": 5,
  "total": 755
}
Documentation by Spectacle