Geographical Search

This feature is used to find a candidate near you through geographical search in simple and advance search methods.

The search is done using Geocodes/City, State, Country or a distance range. You can select different parameters for measuring the distance range like KM and mile.

The geoSearch is an optional parameter (query) that can be passed in the API request of Simple Search, Boolean Search, Free Text Search, Match, Match with ID, and Match with Multiple Sub-User Ids.

Once geoSearch is passed in the request parameter of above API's, it will return the resume/JD that fulfills the geoSearch query.

Note:

By dafault, when geoSearch is passed in the API request, the score for the returned resume/JD is reduced by 50%, and the remaining 50% score is allocated to the geoSearch query. To know more, see the sample Simple Search query below with and without geoSearch.
When the geoSearchScore parameter is included in the API request, the score assigned to the geoSearch query is determined by the value specified in the geoSearchScore parameter. This allows you to dynamically change the score for the geoSearch query using geoSearchScore parameter. For example, if "geoSearchScore": 20 is passed in the API request, then 20% of the score is assigned to the geoSearch query, and the remaining 80% is returned for the resume/JD.

Field-Level GeoLocation Selection

The fields parameter can be added inside the geoSearch object to specify which GeoLocation fields should be used for geographical matching. This parameter allows users to select one or more location fields, such as address location, current location, preferred location, experience location, or education location. If any one of the selected fields satisfies the GeoSearch condition, the resume or job description is considered a match.

The fields parameter is optional. If it is not passed in the request, GeoSearch uses the default GeoLocation fields for matching. A sample geoSearch request with the fields parameter is shown below:

"geoSearch": {
 "longitude": "-76.61219000",
 "latitude": "39.27238000",
 "minRadius": 1,
 "maxRadius": 100,
 "fields": [
   "AddressGeoLocation",
   "CurrentExperienceGeoLocation",
   "CurrentGeoLocation",
   "PreferredGeoLocation",
   "ExperienceGeoLocation",
   "EducationGeoLocation"
 ]
}

Supported values for the fields parameter are:


Field Name	Description
`AddressGeoLocation`	Uses the address location of the resume or job description.
`CurrentExperienceGeoLocation`	Uses the location from the current experience.
`CurrentGeoLocation`	Uses the current location.
`PreferredGeoLocation`	Uses the preferred location.
`ExperienceGeoLocation`	Uses the location from experience details.
`EducationGeoLocation`	Uses the location from education details.

Simple Search query without geoSearch - Request

{
    "index": {
        "indexType": "Resume",
        "indexKey": "Use your indexKey",
    },
    "query": {
        "keyword": "Assistant Professor with Java"
    },
    "pageSize": 100,
    "pageStart": 0,
    "explainScore": true,
    "explainScoreType": "json"
}

Simple Search query without geoSearch - Response

Note: Note the score for the document id: 2411180203301130VIUKH8UM is 30 (when geoSearch is not passed).

{
    "count": 1,
    "pageStart": 0,
    "pageSize": 10,
    "records": [
        {
            "id": "2411180203301130VIUKH8UM",
            "score": 30.0,
            "CurrentEmployer": "ZDAAS",
            "TotalExperienceInYear": 20.8,
            "CurrentJobProfile": "Chief Information Officer",
            "City": "Baltimore",
            "FullName": "Amjad Nagrah",
            "Country": "USA",
            "State": "MD"
        }
    ],
    "explainScore": [
        {
           "id": "2411180203301130VIUKH8UM",
            "explaination": {
                "score": 30.0,
                "maxScore": 100.0,
                "SimpleSearch": {
                    "score": 30.0,
                    "maxScore": 100.0,
                    "detailScore": [
                        {
                            "score": 0.0,
                            "maxScore": 70.0,
                            "entity": "JobProfile",
                            "value": "Assistant Professor"
                        },
                        {
                            "score": 30.0,
                            "maxScore": 30.0,
                            "entity": "SkillHaveExp",
                            "value": "java"
                        }
                    ]
                }
            }

Simple Search query with geoSearch - Request

{
    "index": {
        "indexType": "Resume",
        "indexKey": "Use Your indexKey",
    },
    "query": {
        "keyword": "Assistant Professor with Java"
    },
    "geoSearch": {
        "longitude": "-76.61219000",
        "latitude": "39.27238000",
        "minRadius": 1,
        "maxRadius": 100
    },
    "pageSize": 10,
    "pageStart": 0,
    "explainScore": true,
    "explainScoreType": "json"
}

Simple Search query with geoSearch - Response

Note: The score for the document id: 2411180203301130VIUKH8UM is 65 (when geoSearch is passed in the below request). The score for this id in the above request is 24 (when geoSearch is not passed in the request). The increase in the score is calculated as follows:

geoSearch score = 50
Document id score = 15 (reduced by 50%, Document id score was 30 in above request)
Total Score = 50+15 = 65.

{
    "count": 1,
    "pageStart": 0,
    "pageSize": 10,
    "records": [
        {
            "id": "2411180203301130VIUKH8UM",
            "score": 65.0,
            "CurrentEmployer": "ZDAAS",
            "TotalExperienceInYear": 20.8,
            "CurrentJobProfile": "Chief Information Officer",
            "City": "Baltimore",
            "FullName": "Amjad Nagrah",
            "Country": "USA",
            "State": "MD"
        }
    ],
    "explainScore": [
        {
            "id": "2411180203301130VIUKH8UM",
            "explaination": {
                "score": 65.0,
                "maxScore": 100.0,
                "SimpleSearch": {
                    "score": 15.0,
                    "maxScore": 50.0,
                    "detailScore": [
                        {
                            "score": 0.0,
                            "maxScore": 35.0,
                            "entity": "JobProfile",
                            "value": "Assistant Professor"
                        },
                        {
                            "score": 15.0,
                            "maxScore": 15.0,
                            "entity": "SkillHaveExp",
                            "value": "java"
                        }
                    ]
                },
                "geoSearch": {
                    "score": 50.0,
                    "maxScore": 50.0,
                    "detailScore": [
                        {
                            "Location": ",",
                            "GeoCode": "-76.61219000,39.27238000",
                            "MaxRadius": "100.0",
                            "MinRadius": "1.0"
                        }
                    ]
                }
            }
        }
    ]
}

API request Parameters

Request parameters for geoSearch are described below:


Name	Type	Description	Remarks
Option 1
city	String	Name of city	Required
state	String	Name of state related to city	Optional
country	String	Name of Country related to state	Optional
minRadius	Integer	The minimum radius, from the specified Longitude/Latitude within which the search is performed. The default value is 0.	Optional
distanceUnit	String	Default is KM (Kilometer). Possible values are KM and mile	Optional
Option 2
longitude	String	Name of city	Required
latitude	String	Name of state related to city	Required
minRadius	Integer	The minimum radius, from the specified Longitude/Latitude within which the search is performed. The default value is 1.	Optional
maxRadius	Integer	The maximum radius, from the specified Longitude/Latitude within which the search is performed. The default value is 1.	Optional
distanceUnit	String	Default is KM (Kilometer). Possible values are KM and mile	Optional
Field	Array	List of GeoLocation fields to be considered for matching	Optional

JSON request with geoSearch parameter (option 1)

"geoSearch": {
        "city": "Southampton",
        "state": "England",
        "country": "UK",
        "maxRadius": 50,
        "minRadius": 2
    },

JSON request with geoSearch parameter (option 2)

"geoSearch": {
        "longitude": "-95.41507000",
        "latitude": "29.71838000",
        "minRadius": 1,
        "maxRadius": 100
    },

Error codes

Table 1. Geographical Search Error Code
Error Code	Error Message
2132	GeoSearch score must be 0 to 100
2133	GeoSearch score must be a number type
2165	invalid value for minRadius
2166	invalid value for minRadius. minRadius must be greater than 1 and less than radius value