Location

Configure service to enable fetch and share of location details

Overview

A core application that provides location details of the tenant for which the services are being provided.

API's Playground : DIGIT-Playground

Pre-requisites

Before you proceed with the documentation, make sure the following pre-requisites are met -

• Java 17

• PostgreSQL server is running and the DB is created

  • Follow this guide to see how to setup and create DB in postgreSQL.

• Working Knowledge of egov-mdms service to add location data in master data.

• egov-mdms service is running and all the required MDMS masters are loaded in it

Key Functionalities

• The location information is also known as the boundary data of ULB

• Boundary data can be of different hierarchies - ADMIN or ELECTION hierarchy defined by the Administrators and Revenue hierarchy defined by the Revenue department.

• The election hierarchy has the locations divided into several types like zone, election wards, blocks, streets and localities. The Revenue hierarchy has the locations divided into a zone, ward, block and locality.

• The model which defines the localities like zone, ward and etc is a boundary object which contains information like name, lat, long, parent or children boundary if any. The boundaries come under each other in a hierarchy. For instance, a zone contains wards, a ward contains blocks, and a block contains locality. The order in which the boundaries are contained in each other differs based on the tenants.

Environment Variables	Description
egov.services.egov_mdms.hostname	Host name for MDMS service.
egov.services.egov_mdms.searchpath	MDMS Search URL.
egov.service.egov.mdms.moduleName	MDMS module which contain boundary master.
egov.service.egov.mdms.masterName	MDMS master file which contain boundary detail.

Deployment Details

1. Add/Update the MDMS master file which contains boundary data of ULBs.

2. Add Role-Action mapping for the egov-location APIs.

3. Deploy/Redeploy the latest version of the egov-mdms service.

4. Fill the above environment variables in the egov-location with proper values.

5. Deploy the latest version of the egov-location service.

Configuration Details

The boundary data has been moved to MDMS from the master tables in DB. The location service fetches the JSON from MDMS and parses it to the structure of the boundary object as mentioned above. A sample master would look like below.

{
  "tenantId": "pg.cityA",
   "moduleName": "egov-location",
  "TenantBoundary": [
  {
      "hierarchyType": {
              "code": "ADMIN",
              "name": "ADMIN"
      },
       "boundary": {
                "id": 1,
                "boundaryNum": 1,
                "name": "CityA",
                "localname": "CityA",
                "longitude": null,
                "latitude": null,
                "label": "City",
                "code": "pg.cityA",
                "children": []
        }

    }
 ]
}

Attribute Name	Description
tenantId	The tenantId (ULB code) for which the boundary data configuration is defined.
moduleName	The name of the module where TenantBoundary master is present.
TenantBoundary.hierarchyType.name	Unique name of the hierarchy type.
TenantBoundary.hierarchyType.code	Unique code of the hierarchy type.
TenantBoundary.boundary.id	Id of boundary defined for particular hierarchy.
boundaryNum	Sequence number of boundary attribute defined for the particular hierarchy.
name	Name of the boundary like Block 1 or Zone 1 or City name.
localname	Local name of the boundary.
longitude	Longitude of the boundary.
latitude	Latitude of the boundary.
label	Label of the boundary.
code	Code of the boundary.
children	Details of its sub-boundaries.

Integration Details

Integration Scope

The egov-location APIs can be used by any module which needs to store the location details of the tenant.

Integration Benefits

• Get the boundary details based on boundary type and hierarchy type within the tenant boundary structure.

• Get the geographical boundaries by providing appropriate GeoJson.

• Get the tenant list in the given latitude and longitude.

Integration Steps

1. To integrate, the host of egov-location should be overwritten in the helm chart.

2. /boundarys/_search should be added as the search endpoint for searching boundary details based on tenant Id, Boundary Type, Hierarchy Type etc.

3. /geography/_search should be added as the search endpoint. This method handles all requests related to geographical boundaries by providing appropriate GeoJson and other associated data based on tenantId or lat/long etc.

4. /tenant/_search should be added as the search endpoint. This method tries to resolve a given lat, long to a corresponding tenant, provided there exists a mapping between the reverse geocoded city to the tenant.

5. The MDMS tenant boundary master file should be loaded in the MDMS service.

Reference Docs

Doc Links

Title
Local setup

API List

APIs
/boundarys/_search
/geography/_search
/tenant/_search

Please refer to the Swagger API contract for the location service to understand the structure of APIs and to have a visualisation of all internal APIs.