To query the location service you must first authenticate yourself as described in “Performing Authentication“.

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 http://core.ws.efinancialcareers.com/v1/locations/search/name?name=London

The same request to Pilot is the following:

GET http://core.ws.pilot.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"?>
<locations xmlns="http://efinancialcareers.com/schema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://efinancialcareers.com/schema https://core.ws.efinancialcareers.com/v1/schema">
<location href="https://core.ws.efinancialcareers.com/v1/locations/2643743">
<id>2643743</id>
<name>London</name>
<names>
<name>
<name>London</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>London</name>
<language>en</language>
<short>false</short>
<preferred>true</preferred>
</name>
<name>
<name>London City</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>City of London</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>The City</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<latitude>51.50853</latitude>
<longitude>-0.12574</longitude>
<parents>
<location href="https://core.ws.efinancialcareers.com/v1/locations/-12">
<id>-12</id>
<name>European Union</name>
<names>
<name>
<name>EU</name>
<short>true</short>
<preferred>false</preferred>
</name>
<name>
<name>European Union</name>
<language>en</language>
<short>false</short>
<preferred>true</preferred>
</name>
</names>
<type>region</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/-10">
<id>-10</id>
<name>EMEA</name>
<names>
<name>
<name>EMEA</name>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<type>region</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/-1">
<id>-1</id>
<name>Global</name>
<names>
<name>
<name>Global</name>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<type>global</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/2635167">
<id>2635167</id>
<name>United Kingdom</name>
<names>
<name>
<name>Great Britain</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>United Kingdom of Great Britain and Northern Ireland</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>Britain</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>UK</name>
<short>true</short>
<preferred>false</preferred>
</name>
<name>
<name>GB</name>
<short>true</short>
<preferred>false</preferred>
</name>
<name>
<name>Britain</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>United Kingdom</name>
<language>en</language>
<short>false</short>
<preferred>true</preferred>
</name>
<name>
<name>UK</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>U.K.</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<type>country</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/2648110">
<id>2648110</id>
<name>Greater London</name>
<names>
<name>
<name>Greater London</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>Greater London</name>
<language>en</language>
<short>true</short>
<preferred>true</preferred>
</name>
</names>
<type>division</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/3333218">
<id>3333218</id>
<name>City of Westminster</name>
<names>
<name>
<name>Westminster</name>
<short>true</short>
<preferred>true</preferred>
</name>
<name>
<name>City of Westminster</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<type>division</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/6255148">
<id>6255148</id>
<name>Europe</name>
<names>
<name>
<name>Europe</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>Europe</name>
<language>en</language>
<short>false</short>
<preferred>false</preferred>
</name>
</names>
<type>region</type>
</location>
<location href="https://core.ws.efinancialcareers.com/v1/locations/6269131">
<id>6269131</id>
<name>England</name>
<names>
<name>
<name>Anglia</name>
<short>false</short>
<preferred>false</preferred>
</name>
<name>
<name>England</name>
<language>en</language>
<short>true</short>
<preferred>true</preferred>
</name>
</names>
<type>division</type>
</location>
</parents>
<type>city</type>
<parentChains>
<chain>
<location>
<refId>3333218</refId>
</location>
<location>
<refId>2648110</refId>
</location>
<location>
<refId>6269131</refId>
</location>
<location>
<refId>2635167</refId>
</location>
<location>
<refId>-12</refId>
</location>
<location>
<refId>6255148</refId>
</location>
<location>
<refId>-10</refId>
</location>
</chain>
</parentChains>
<dictTranslations locale="en">
<translation>
<path>ws.locationType.dict.CITY</path>
<content>City</content>
</translation>
</dictTranslations>
</location>
<labelTranslations locale="en">
<translation>
<path>ws.location.label.country</path>
<content>Country</content>
</translation>
<translation>
<path>ws.location.label.latitude</path>
<content>Latitude</content>
</translation>
<translation>
<path>ws.location.label.locationType</path>
<content>Location Type</content>
</translation>
<translation>
<path>ws.location.label.longitude</path>
<content>Longitude</content>
</translation>
<translation>
<path>ws.location.label.name</path>
<content>Name</content>
</translation>
<translation>
<path>ws.location.label.names</path>
<content>Names</content>
</translation>
<translation>
<path>ws.location.label.names.abbrev</path>
<content>Abbreviation</content>
</translation>
<translation>
<path>ws.location.label.names.language</path>
<content>Language</content>
</translation>
<translation>
<path>ws.location.label.names.name</path>
<content>Name</content>
</translation>
<translation>
<path>ws.location.label.names.short</path>
<content>Short</content>
</translation>
<translation>
<path>ws.location.label.parentLocationChains</path>
<content>Parent Location Chains</content>
</translation>
<translation>
<path>ws.location.label.parentLocations</path>
<content>Parent Locations</content>
</translation>
<translation>
<path>ws.location.label.parentLocationsMap</path>
<content>Parent Location Map</content>
</translation>
</labelTranslations>
</locations>

Our clients include