To query the location service you must first authenticate yourself as described in “Authenticating to Retrieve Dictionary Values“.

Geographical Location Search

To retrieve a location to use in Resume Search, send an authorised HTTP GET request to the following URL replacing the {name} with the location you require. You will need to use the location id (location / id) as resume search parameter.

GET https://core.ws.efinancialcareers.com/v1/locations/search/name?name=London

Mandatory HTTP headers:

Content-Type: application/xml

Authorization: EfcAuth realm=”EFC”, token=”522c3c4bd036a69db428ce4274745e9d”

Locations Searches and parameters

There are the following types of location searches:

Name Description Request Path Obligatory parameters Optional parameters
Search locations Retrieve all locations in the system with/without filtering by parameter locations no language, locale, category, type, parent, country, page-size, page, with-parents, show-country, order-by, sort-order
Search location by ID Retrieve the location by ID locations/{id} id (of the location) language, locale, with-parents, show-country
Search the nearest location Retrieve the nearest location by latitude, longitude locations/search/nearest?latitude=…&longitude=… latitude, longitude language, locale, category, type, parent, country, with-parents, show-country
Search locations in  the range Retrieve locations in specified radius locations/search/range?latitude=…&longitude=…&radius=… latitude, longitude, radius language, locale, category, type, parent, country, page-size, page, with-parents, show-country, order-by, sort-order
Search locations by name Retrieve locations by name locations/search/name?name=… name language, locale, category, type, parent, country, page-size, page, with-parents, show-country, order-by, sort-order

 

There is a table with parameters, which can be applied to searches:

Name Description String format Possible values Examples
All requests
Language Request and response language of locations names language={language code} All supported language codes in the system. Use dictionary service to get them. language=EN, language=FR, language=IT
Locale Defines the language of translations in a response locale={locale code} All supported language codes in the system. Use dictionary service to get them. locale=EN, locale=FR, locale=IT
Search locations, Search the nearest location, Search locations in  the range, Search locations by name
Category Functionality where location data will be used, it works like a filter category={category name} inventory, job, resume, resume-license, work-permit category=inventory, category=job
Type Type of the location regarding to levels type={location type} global, region, country, division, city, postalcode type=country, type=city
Parent Id of the parent location parent={parent id} Available ids in the system parent=993152 , parent=-4343
Country Code of the country country={country code} All supported country codes in the system. Use dictionary service to get them. country=GB, country=US
With parents Show parent chain for location name with-parents={flag} Boolean values “true” or “false” with-parents=true, with-parents=false
Show country Display country in parent location chain show-country={flag} Boolean values “true” or “false” show-country=true, show-country=false
Search locations, Search locations in the range, Search locations by name
Page size The amout of locations in response per page page-size={number} 1-250 page-size=30, page-size=50
Page number The current page number page={number} Max number is limited by search results page=1, page=5
Sort criteria Name of the sort criteria order-by={sort criteria} name order-by=name
Sort direction Direction of the sorting sort-order={sort direction} ASC, DESC sort-order=ASC, sort-order=DESC
Search the nearest location, Search locations in the range
Latitude Geo latitude latitude={latitude} -90 <= latitude <= 90 latitude=12.23, latitude=-34.0031
Longitude Geo longitude longitude={longitude} -180 <= longitude <= 180 longitude=112.23, longitude=-134.0031
Search locations in  the range
Radius Radius in km radius={radius} 0-250 radius=19, radius=172
Search locations by name
Name Location name (zip code name) name={location name} Text symbols and digits name=London, name=993152
Search location by ID
Id Location id locations/{id} Available ids in the system locations/1, locations/-10, locations/451256

 

There is a list of default parameters below. They will be applied to the request by default.

  • locale = current locale of the user (EN by default);
  • language = locale;
  • page-size = 30;
  • page = 1.

Examples of search requests

How to get countries of the region:

1. Call the service with “type=region” to get the list of regions.

2. Call the service with “type=country” and “parent={region_id}” from the previous call to get the list of countries for a certain region.

How to get locations, which are valid for work permit: call the service with “category=work-permit”.

Locations Searches Response

Upon success, the server responds with HTTP 200 OK status code and an XML representation of the location details in the response body:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<ns2:locations totalCount="36" xsi:schemaLocation="http://efinancialcareers.com/schema https://core.ws.efinancialcareers.com/v1/schema">
<ns2:location href="https://app.ws.efinancialcareers.com/v1/locations/2643743">
<ns2:id>2643743</ns2:id>
<ns2:name>London</ns2:name>
<ns2:names>
<ns2:name>
<ns2:name>London City</ns2:name>
<ns2:language>en</ns2:language>
<ns2:short>false</ns2:short>
<ns2:preferred>false</ns2:preferred>
</ns2:name>
..........
</ns2:names>
<ns2:latitude>51.50853</ns2:latitude>
<ns2:longitude>-0.12574</ns2:longitude>
<ns2:parents>
<ns2:location>
<ns2:id>3333218</ns2:id>
<ns2:name>City of Westminster</ns2:name>
<ns2:names>
<ns2:name>
<ns2:name>City of Westminster</ns2:name>
<ns2:language>en</ns2:language>
<ns2:short>false</ns2:short>
<ns2:preferred>false</ns2:preferred>
</ns2:name>
............
</ns2:names>
<ns2:type>DIVISION</ns2:type>
</ns2:location>
............
<ns2:location>
<ns2:id>6269131</ns2:id>
<ns2:name>England</ns2:name>
<ns2:names>
<ns2:name>
<ns2:name>England</ns2:name>
<ns2:language>en</ns2:language>
<ns2:short>false</ns2:short>
<ns2:preferred>true</ns2:preferred>
</ns2:name>
.............
</ns2:names>
.............
<ns2:type>COUNTRY</ns2:type>
</ns2:location>
<ns2:location>
<ns2:id>-12</ns2:id>
<ns2:name>European Union</ns2:name>
<ns2:names>
.............
</ns2:names>
<ns2:labelTranslations>
<ns2:translation>
<ns2:type>dict</ns2:type>
<ns2:path>ws.location.label.name</ns2:path>
<ns2:locale>en</ns2:locale>
<ns2:content>Name</ns2:content>
</ns2:translation>
.............
</ns2:labelTranslations>
</ns2:locations>

Example of search location by id:

GET https://core.ws.efinancialcareers.com/v1/locations/-18

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<ns2:location href="https://app.ws.efinancialcareers.com/v1/locations/-18" xsi:schemaLocation="http://efinancialcareers.com/schema https://core.ws.efinancialcareers.com/v1/schema">
<ns2:id>-18</ns2:id>
<ns2:name>Gulf</ns2:name>
<ns2:names>
<ns2:name>
<ns2:name>Gulf</ns2:name>
<ns2:language>en</ns2:language>
<ns2:short>false</ns2:short>
<ns2:preferred>true</ns2:preferred>
</ns2:name>
...........
</ns2:names>
<ns2:parents>
<ns2:location>
<ns2:id>-10</ns2:id>
<ns2:name>EMEA</ns2:name>
<ns2:names>
<ns2:name>
<ns2:name>EMEA</ns2:name>
<ns2:language>en</ns2:language>
<ns2:short>false</ns2:short>
<ns2:preferred>true</ns2:preferred>
</ns2:name>
............
</ns2:names>
............
<ns2:labelTranslations>
<ns2:translation>
<ns2:type>dict</ns2:type>
<ns2:path>ws.location.label.name</ns2:path>
<ns2:locale>en</ns2:locale>
<ns2:content>Name</ns2:content>
</ns2:translation>
.............
</ns2:dictTranslations>
</ns2:location>

Our clients include