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 https://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

 

 

Search location by ID

Search the nearest location

Search locations in the range

 

Search locations by name

Retrieve all locations in the system with/without filtering by parameter

 

Retrieve the location by ID

 

Retrieve the nearest location by latitude, longitude

 

Retrieve locations in specified radius

 

 

Retrieve locations by name

locations

 

 

 

locations/{id}

 

locations/search/nearest?latitude=…&longitude=…

locations/search/range?latitude=…&longitude=…&radius=…

 

locations/search/name?name=…

no

 

 

 

id (of the location)

latitude, longitude

 

latitude, longitude, radius

 

name

language, locale, category, type, parent, country, page-size, page, with-parents, show-country, order-by, sort-order

language, locale, with-parents, show-country

language, locale, category, type, parent, country, with-parents, show-country

language, locale, category, type, parent, country, page-size, page, with-parents, show-country, order-by, sort-order

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

 

 

 

Locale

Request and response language of locations names

 

 

Defines the language of translations in a response

language={language code}

 

locale={locale code}

All supported language codes in the system. Use dictionary service to get them.

All supported language codes in the system. Use dictionary service to get them.

language=EN, language=FR, language=IT

 

locale=EN,
locale=FR,
locale=IT

Search locations, Search the nearest location, Search locations in  the range, Search locations by name

Category

 

 

Type

 

Parent

 

Country

 

 

With parents

 

Show country

Functionality where location data will be used, it works like a filter

Type of the location regarding to levels

Id of the parent location

 

Code of the country

 

 

Show parent chain for location name

Display country in parent location chain

category={category name}

type={location type}

parent={parent id}

country={country code}

 

with-parents={flag}

show-country={flag}

inventory, job, resume, resume-license, work-permit

 

global, region, country, division, city, postalcode

Available ids in the system

 

All supported country codes in the system. Use dictionary service to get them.

Boolean values “true” or “false”

Boolean values “true” or “false”

category=inventory, category=job

 

type=country, type=city

parent=993152 , parent=-4343

country=GB, country=US

 

with-parents=true, with-parents=false

show-country=true, show-country=false

Search locations, Search locations in the range, Search locations by name

Page size

 

Page number

 

Sort criteria

 

Sort direction

The amout of locations in response per page

The current page number

 

Name of the sort criteria

 

Direction of the sorting

page-size={number}

page={number}

 

order-by={sort criteria}

sort-order={sort direction}

1-250

 

Max number is limited by search results

name

 

ASC, DESC

page-size=30,
page-size=50

page=1, page=5

 

order-by=name

 

sort-order=ASC,
sort-order=DESC

Search the nearest location, Search locations in the range

Latitude

 

Longitude

Geo latitude

 

Geo longitude

latitude={latitude}

longitude={longitude}

-90 <= latitude <= 90

 

-180 <= longitude <= 180

latitude=12.23, latitude=-34.0031

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 locations 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>>