This is a Flask application that primarily references an ESRI geocoder, but also enables more customized location lookup than the ESRI geocoder provides, as well as fewer required parameters on input and a simpler JSON format in the responses.
The underlying ESRI geocoder service (https://geocoder.boston.gov/arcgis/rest/services/SAMLocator/GeocodeServer) used by this application is created from active Boston addresses in the Street & Address Management (SAM) system, and is updated nightly.
See the Live SAM Addresses dataset on Analyze Boston to explore this dataset.
There are 3 REST GET endpoints in this application, described below:
- https://geocoder.boston.gov/samgeocoder/geocode
Example request: https://geocoder.boston.gov/samgeocoder/geocode?address=1%20City%20Hall%20Sq
Required URL parameters:
- address (string)
This can be specified with raw spaces, commas, periods, # symbols, etc. (i.e. "1 City Hall Square"); characters will be automatically URL-encoded when the request is sent.
Returned JSON fields:
- matching_address_full (string)
If there is no matching address found, this returns "No matches found", and is the only field returned. If there is a matching address, this returns the full address text (i.e. "1 City Hall Plz, BOSTON, MA, 02114").
- street_number (string)
The street number (e.g. "1", "1-2A") of the matching address
- street_name (string)
The full street name (e.g. "E Main St", "Main St N", "Charles St") of the matching address
- unit (string)
The unit number of the matching address, if there is a unit number
- building_id (integer)
The building ID of the matched address in Boston's Street Address Management (SAM) system
- match_score (float)
How well the input address matched to the returned (closest matching) address, out of 100
- matching_address_x (float)
x-coordinate (longitude) of the matching_address, in coordinate system WGS84 (SRID 4326)
- matching_address_y (float)
y-coordinate (latitude) of the matching_address, in coordinate system WGS84 (SRID 4326)
- sam_id (string)
The ID of the address in Boston's Street Address Management (SAM) system
- primary_sam_id (string)
The ID of the corresponding primary (building) address in Boston's Street Address Management (SAM) system; this may or may not be the same address as the matching_address (if the matching_address is a primary address, not a secondary address)
- primary_sam_address (string)
The full address text (i.e. "1 City Hall Plz, BOSTON, MA, 02114") of the corresponding primary (building) address in Boston's Street Address Management (SAM) system
- btd_district (integer)
The transportation district of the matched address
- city_council_district (integer)
The city council district of the matched address
- fire_district (integer)
The fire district of the matched address
- mailing_neighborhood (string)
The mailing neighborhood of the matched address
- parcel (string)
The parcel of the matched address
- park_name (string)
If the matched address lies within a park, the name of the park (blank if not)
- park_ownership (string)
If the matched address lies within a park, the designated park owner (blank if not)
- police_district (string)
The police district of the matched address
- planning_neighborhood (string)
The planning neighborhood of the matched address
- pwd_district (string)
The Public Works Department (PWD) district of the matched address
- street_jurisdiction (string)
The jurisdiction of the street of the matched address (i.e. Public Way, Private Way, Mixed Public/Private)
- street_ownership (string)
The owner of the street of the matched address (i.e. PWD, DCR, MPA, Park, MTA, BHA)
- trash_day (string)
The trash pickup day of the matched address
- ward (string)
The ward of the matched address
- precinct (string)
The precinct of the matched address
- zip_code (string)
The zip code of the matched address
Additional notes:
Addresses are assumed to have city=Boston and state=MA.
- https://geocoder.boston.gov/samgeocoder/xy_lookup
Example request: https://geocoder.boston.gov/samgeocoder/xy_lookup?x=-71.0582056&y=42.3605989
Required URL parameters:
- x (float)
This is assumed to be in WGS84 (SRID 4326) coordinate system, i.e. -71.0582056.
- y (float)
This is assumed to be in WGS84 (SRID 4326) coordinate system, i.e. 42.3605989.
Returned JSON fields:
- nearest_address_full (string)
If there is no close address found, this returns "No matches found". If there is a close address, this returns the full address text (i.e. "1 City Hall Plz, BOSTON, MA, 02114").
- nearest_address_street_number (string)
The street number (e.g. "1", "1-2A") of the nearest address
- nearest_address_street_name (string)
The full street name (i.e. "E Main St", "Main St N", "Charles St") of the nearest address
- nearest_address_unit (string)
The unit number of the nearest address, if there is a unit number
- nearest_address_zip_code (string)
The zip code of the nearest address
- nearest_address_x (float)
x-coordinate (longitude) of the nearest address, in coordinate system WGS84 (SRID 4326)
- nearest_address_y (float)
y-coordinate (latitude) of the nearest address, in coordinate system WGS84 (SRID 4326)
- nearest_address_distance_meters_from_input_xy (float)
Distance (in meters) from the nearest address to the input XY coordinates
- nearest_address_sam_id (integer)
The ID of the nearest address in Boston's Street Address Management (SAM) system
- nearest_address_primary_sam_id (integer)
The ID of the nearest address's corresponding primary (building) address in Boston's Street Address Management (SAM) system; this may or may not be the same address as the nearest_address_sam_id (if the nearest address is a primary address, not a secondary address)
- nearest_address_primary_sam_address (string)
The full address text (i.e. "1 City Hall Plz, BOSTON, MA, 02114") of the corresponding primary (building) address in Boston's Street Address Management (SAM) system
- nearest_address_building_id (integer)
The building ID of the nearest address in Boston's Street Address Management (SAM) system
- btd_district (integer)
The transportation district underlying the input XY coordinates
- city_council_district (integer)
The city council district underlying the input XY coordinates
- fire_district (integer)
The fire district underlying the input XY coordinates
- mailing_neighborhood (string)
The mailing neighborhood underlying the input XY coordinates
- nearest_centerline_street_jurisdiction (string)
The street jurisdiction of nearest centerline segment to the input XY coordinates
- nearest_centerline_street_name (string)
The street name of nearest centerline segment to the input XY coordinates
- nearest_centerline_street_ownership (string)
The street ownership of nearest centerline segment to the input XY coordinates
- nearest_centerline_x (float)
The nearest point x-coordinate along the nearest centerline segment to the input XY coordinates, in coordinate system WGS84 (SRID 4326)
- nearest_centerline_y (float)
The nearest point y-coordinate along the nearest centerline segment to the input XY coordinates, in coordinate system WGS84 (SRID 4326)
- nearest_intersection_distance_meters_from_input_xy (float)
Distance (in meters) from the nearest street intersection to the input XY coordinates
- nearest_intersection_name (string)
The name of nearest street intersection to the input XY coordinates
- nearest_intersection_x (float)
x-coordinate (longitude) of the nearest street intersection, in coordinate system WGS84 (SRID 4326)
- nearest_address_y (float)
y-coordinate (latitude) of the nearest street intersection, in coordinate system WGS84 (SRID 4326)
- parcel (string)
The parcel underlying the input XY coordinates
- park_name (string)
If the input XY coordinates lie within a park, the name of the park (blank if not)
- park_ownership (string)
If the input XY coordinates lie within a park, the designated park owner (blank if not)
- planning_neighborhood (string)
The planning neighborhood of the matched address
- police_district (string)
The police district underlying the input XY coordinates
- pwd_district (string)
The Public Works Department (PWD) district underlying the input XY coordinates
- trash_day (string)
The trash pickup day of the area underlying the input XY coordinates
- ward (string)
The ward underlying the input XY coordinates
- precinct (string)
The precinct underlying the input XY coordinates
- zip_code (string)
The zip code underlying the input XY coordinates
Additional notes:
This endpoint finds the nearest address in the SAM system. The "matching_address" "match_x", "match_y", and "sam_id" attributes are a characteristic of the closest matching address in SAM. However, any additional attributes (i.e. zip code) returned are a characteristic of the entered XY coordinates, not necessarily of the closest matching address in SAM (if any).
- https://geocoder.boston.gov/samgeocoder/intersection_lookup
Example request: https://geocoder.boston.gov/samgeocoder/intersection_lookup?intersection=Congress%20St%20and%20North%20St
Required URL parameters:
- intersection (string)
This must contain " and " or " & "; characters will be automatically URL-encoded when the request is sent.
Returned JSON fields:
- match_score (float)
How well the input intersection matched to the returned intersection, out of 100
- matching_intersection_full (string)
If there is no matching intersection found, this returns "No matches found", and is the only field returned. If there is a matching intersection, this returns the full intersection text (i.e. "Congress ST & North ST, Downtown, MA 02108").
- matching_intersection_x (float)
x-coordinate (longitude) of the matching_intersection, in coordinate system WGS84 (SRID 4326)
- matching_intersection_y (float)
y-coordinate (latitude) of the matching_intersection, in coordinate system WGS84 (SRID 4326)
- btd_district (integer)
The transportation district underlying the matched intersection
- city_council_district (integer)
The city council district underlying the matched intersection
- fire_district (integer)
The fire district underlying the matched intersection
- mailing_neighborhood (string)
The mailing neighborhood underlying the matched intersection
- parcel (string)
The parcel underlying the matched intersection
- park_name (string)
If the matched intersection lies within a park, the name of the park (blank if not)
- park_ownership (string)
If the matched intersection lies within a park, the designated park owner (blank if not)
- planning_neighborhood (string)
The planning neighborhood of the matched intersection
- police_district (string)
The police district underlying the matched intersection
- pwd_district (string)
The Public Works Department (PWD) district underlying the matched intersection
- trash_day (string)
The trash pickup day of the area underlying the matched intersection
- ward (string)
The ward underlying the matched intersection
- precinct (string)
The precinct underlying the matched intersection
- zip_code (string)
The zip code underlying the matched intersection