GeoMarker API Usage and Troubleshooting

Summary:

The GeoMarker API hosts endpoints for the geomarking of address data provided in order to de-couple workflows from any underlying technology requirements beyond HTTP client capabilities.

Currently the API supports endpoints for the DeGauss project in order to allow consumers to leverage the DeGauss functionality without local Docker or the infrastructure required for Docker workflows. The following images provided by the DeGauss project are supported with the corresponding web endpoints:

Usage:

Workflows will always begin with the geocoding of address data.

Following the geocoding of the addresses, Drivetime, DeprivationIndex or CensusBlockGroup may be used to map census and geographical data to the geocoded addresses provided (These endpoints consume the resulting file from calling Geocode).

Geocode

Geocoding of address data may be accomplished using the api/DeGauss/GetGeocode API endpoint.

Geocode/Request

The endpoint expects body request content of type multipart/form-data

The form data provided must have the form field ‘file’ referencing a file or file stream with a .csv file format not exceeding 300 lines in the file, not including the header for the csv which defines the column names.

The file must have the columns:

Geocode/Response

The response for a valid request will be a file stream for a csv file with the following columns:

DeprivationIndex

Mapping of census tract deprivation index data to geocoded addresses may be accomplished by using the api/DeGauss/GetDeprivationIndex endpoint.

DeprivationIndex/Request

The endpoint expects body request content of type multipart/form-data

The form data provided must have the form field ‘file’ referencing a file or file stream with a .csv file format not exceeding 300 lines in the file, not including the header for the csv which defines the column names.

The file must be an address file that has been processed by the Geocode endpoint as defined by Geocode/Response

DeprivationIndex/Response

The response for a valid request will be a file stream for a csv file with the geocoded data with the addition of the following columns:

Drivetime

Mapping of geographic distance and time data to geocoded addresses may be accomplished by using the api/DeGauss/GetDrivetime endpoint

Drivetime/Request

The endpoint expects body request content of type multipart/form-data

The form data provided must have the form field ‘file’ referencing a file or file stream with a .csv file format not exceeding 300 lines in the file, not including the header for the csv which defines the column names.

The file must be an address file that has been processed by the Geocode endpoint as defined by Geocode/Response

The form data provided must have the form field ‘site’ which is a string abbreviation for the clinical care center that drive time and distance is being determined.

‘site’ must be one of the following abbreviations:

Drivetime/Response

The response for a valid request will be a file stream for a csv file with the geocoded data with the addition of the following columns:

CensusBlockGroup

Mapping of census block group and tract information to geocoded addresses may be accomplished by using the api/DeGauss/GetCensusBlockGroup endpoint

CensusBlockGroup/Request

The endpoint expects body request content of type multipart/form-data

The form data provided must have the form field ‘file’ referencing a file or file stream with a .csv file format not exceeding 300 lines in the file, not including the header for the csv which defines the column names.

The file must be an address file that has been processed by the Geocode endpoint as defined by Geocode/Response

The form data provided must have the form field ‘year’ which is an integer value for the year being queried for census tract and block group information.

‘year’ must be one of the following for block group and tract: 1990, 2000, 2010, 2020

for tract only: 1970, 1980

CensusBlockGroup/Response:

The response for a valid request will be a file stream for a csv file with the geocoded data with the addition of the following columns:

Examples:

Troubleshooting:

Common errors

401-Unauthorized

The request made was unauthorized, this occurs when attempting to consume the backend endpoint directly without a bearer token and ‘Bearer’ schema provided in the ‘Authorization’ header in the request (Or with an invalid token).

This can also happen with requests made to the API gateway without the Ocp-Apim-Subscription-Key header and corresponding key.

Requests made to the gateway API will automatically pass through with valid authentication to the backend. The gateway URL is https://prodcmapimanagement.azure-api.net

400-BadRequest

The request made was invalid. The ProblemDetails of the response will describe the issue so that you may correct the request.

Example - Record count > 300

408-RequestTimeout

The request made has taken too long to process by the underlying compute resources. Try reducing the size of the request.

500-InternalServerError

The application infrastructure has failed to process your request due to an un-handled or un-recoverable error. Try again later or contact the development team with reproduction steps to resolve if the error persists.

503-ServiceNotAvailable

The underlying compute resources are busy and are unable to service your request. Try again later.