Documentation

Basics

Geocoder is service which provides coordinates for given address. It uses number of sources, among them:

This service searches prepared data for given address and if it doesn't find it, it scrapes and caches the result for future. Right now it covers only following states:

Authentication.

In order to use this service you need to provide API key among your query or post parameters: key. Ask @asudakov for it in slack.

Methods

Right now service supports only one following method:

geocode

geocode - GET /api/geocode

Input parameters:

q - [mandatory] string, address to geocode
state - [optional] string, default state if not parsed from "q" parameter
max_rating - [optional] integer, maximium acceptable rating (the less rating, the better, 0 - the best), default - 0
scrape - [optional] integer (0 or 1), flag to use scraper if not found in prepared data, it burns API calls, be sure to pass valid queries, default - 0 (not use scraping) WARNING: scraping works in 1 thread only (using lock mechanism). This means whenever different client request something for scraping they are waiting for each other.

Output JSON hash / dictionary / associative array with following keys:

code - integer, 0 - error, 1 - found result, 2 - not found result according to your query;
message - string, error description or code message;
lat - float number, latitude;
lon - float number, longitude;
rating - integer number, rating, the less the better, 0 - the best;
source - string, source of the data.
source_id - string, identifier in the source.
address_full - string, prepared full address.
house_number - string, parsed house number.
road - string, parsed road.
zip - string, parsed zip.
city - string, parsed city.
county - string, parsed county.
state - string, parsed state.
country - string, parsed country.
id - string, system identifier of the row.

Examples

Get http://vm80:9999/api/geocode?key=ADD_YOUR_KEY_HERE&scrape=0&q=62 ridgeview drive, rochester ny 14617.

Resulting JSON (prettyfied version):

{
    "code": 1
    ,"message": "Geocoded from cache."
    ,"lat": 43.20241
    ,"lon": -77.59463
    ,"rating": 0
    ,"address_full": "62 ridgeview drive rochester ny us"
    ,"house_number": "62"
    ,"road": "ridgeview drive"
    ,"zip": "14617"
    ,"city": "rochester"
    ,"county": "monroe"
    ,"state": "ny"
    ,"country": "us"
    ,"source": "Bing"
    ,"source_id": ""
    ,"id": 10880500
}

-- drop TABLE if exists `geocode_jobs`; CREATE TABLE `geocode_jobs` ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT primary key, user_id bigint(20) unsigned NOT NULL, job_id varchar(100) not null, createdDate VARCHAR(100) not null, completedDate VARCHAR(100) not null, created_at DATETIME NOT NULL, description varchar(100) not null default '', failedEntityCount integer not null default '0', processedEntityCount integer not null default '0', totalEntityCount integer not null default '0', status varchar(100) not null default 'Pending' unique key(user_id,job_id) ) Engine = InnoDB default charset = utf8 COLLATE=utf8_unicode_ci; -- alter table geocode_jobs add column completedDate VARCHAR(100) not null after createdDate; -- alter table geocode_jobs add unique key(user_id,job_id); -- drop TABLE if exists `geocode_schedules`; CREATE TABLE `geocode_schedules` ( user_id bigint(20) unsigned NOT NULL, job_id varchar(100) not null, address varchar(255) NOT NULL default '', key(user_id, job_id), UNIQUE key(address) ) Engine = InnoDB default charset = utf8 COLLATE=utf8_unicode_ci; [28238 2022-03-21 15:28:21] [info] $VAR1 = [ 1, 'parsed JSON', { 'traceId' => '3e69bdf81d9c480c813d4d3778428232|CH10003162|0.0.0.0', 'statusDescription' => 'OK', 'brandLogoUri' => 'http://spatial.virtualearth.net/Branding/logo_powered_by.png', 'resourceSets' => [ { 'resources' => [ { 'failedEntityCount' => '1', 'totalEntityCount' => '3', 'status' => 'Completed', 'description' => 'Geocode', 'processedEntityCount' => '3', 'completedDate' => 'Sat, 19 Mar 2022 11:33:20 GMT', 'id' => 'e048d56e1dfc4f099f711b2af2ec4d36', 'createdDate' => 'Sat, 19 Mar 2022 11:33:05 GMT', '__type' => 'DataflowJob:http://schemas.microsoft.com/search/local/ws/rest/v1', 'links' => [ { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e048d56e1dfc4f099f711b2af2ec4d36', 'role' => 'self' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e048d56e1dfc4f099f711b2af2ec4d36/output/succeeded', 'name' => 'succeeded', 'role' => 'output' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e048d56e1dfc4f099f711b2af2ec4d36/output/failed', 'name' => 'failed', 'role' => 'output' } ] }, { 'failedEntityCount' => '3', 'totalEntityCount' => '26', 'status' => 'Completed', 'description' => 'Geocode', 'processedEntityCount' => '26', 'completedDate' => 'Thu, 17 Mar 2022 13:49:01 GMT', 'id' => '2d4fb42a00dc48edb949e26ceb8a9552', 'createdDate' => 'Thu, 17 Mar 2022 13:48:42 GMT', '__type' => 'DataflowJob:http://schemas.microsoft.com/search/local/ws/rest/v1', 'links' => [ { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/2d4fb42a00dc48edb949e26ceb8a9552', 'role' => 'self' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/2d4fb42a00dc48edb949e26ceb8a9552/output/succeeded', 'name' => 'succeeded', 'role' => 'output' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/2d4fb42a00dc48edb949e26ceb8a9552/output/failed', 'name' => 'failed', 'role' => 'output' } ] }, { 'failedEntityCount' => '3', 'totalEntityCount' => '26', 'status' => 'Completed', 'description' => 'Geocode', 'processedEntityCount' => '26', 'completedDate' => 'Tue, 15 Mar 2022 09:06:14 GMT', 'id' => '082e61f1bf544384ab06794e09dddd0c', 'createdDate' => 'Tue, 15 Mar 2022 09:05:53 GMT', '__type' => 'DataflowJob:http://schemas.microsoft.com/search/local/ws/rest/v1', 'links' => [ { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/082e61f1bf544384ab06794e09dddd0c', 'role' => 'self' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/082e61f1bf544384ab06794e09dddd0c/output/succeeded', 'name' => 'succeeded', 'role' => 'output' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/082e61f1bf544384ab06794e09dddd0c/output/failed', 'name' => 'failed', 'role' => 'output' } ] }, { 'failedEntityCount' => '1', 'totalEntityCount' => '4', 'status' => 'Completed', 'description' => 'Geocode', 'processedEntityCount' => '4', 'completedDate' => 'Mon, 14 Mar 2022 21:10:02 GMT', 'id' => 'e34d93ed3fb54930be16343b256eada0', 'createdDate' => 'Mon, 14 Mar 2022 21:09:48 GMT', '__type' => 'DataflowJob:http://schemas.microsoft.com/search/local/ws/rest/v1', 'links' => [ { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e34d93ed3fb54930be16343b256eada0', 'role' => 'self' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e34d93ed3fb54930be16343b256eada0/output/succeeded', 'name' => 'succeeded', 'role' => 'output' }, { 'url' => 'http://spatial.virtualearth.net/REST/v1/dataflows/Geocode/e34d93ed3fb54930be16343b256eada0/output/failed', 'name' => 'failed', 'role' => 'output' } ] } ], 'estimatedTotal' => '4' } ], 'copyright' => "Copyright \x{a9} 2022 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.", 'statusCode' => '200', 'authenticationResultCode' => 'ValidCredentials' } ];