Neighborhoods REST API Reference

The Neighborhoods REST API provides a flexible and on-demand access to UMI’s spatially-aware database of neighborhoods.

The API provides three types of search methods:

Search by spatial parameters
Search by administrative boundaries
Search by name

Given a set of search results via the search methods, additional detail about individual neighborhoods is available:

Getting additional detail
Relationships among neighborhoods

API Calls

An API call is structured as follows:

http://api0.urbanmapping.com/neighborhoods/rest/{method_name}?{method parameters}&apikey={API key}

For example: http://api0.urbanmapping.com/neighborhoods/rest/getNeighborhoodsByLatLng?lat=37.76&lng=-122.46&apikey=ABCDEFG

You must use your own API key. If you have not already registered and signed up for a key - follow the instructions here: Getting Started.

The REST API supports HTTP-GET queries. All methods accept the following request parameters:

Universal Input Parameters (* = required)

apikey (String) *
Developer API Key

format (“json” or “xml” )
The desired response format; defaults to “json”

outvar (Javascript variable name)
Optional parameter for json output. Assigns the result to the specified variable name. Web applications can call eval on the result directly.

Sample code and calls can be found here.

Searching by Location

Given geographic input parameters, these methods return a collection of neighborhoods. Note that free API users are limited to requests within the United States and Canada (your actual location does not matter).

method getNeighborhoodsByLatLng

Returns a list of neighborhoods whose boundaries contain the requested latitude and longitude.

Request Parameters

Lat (Float)
A WGS-84 latitude, in degrees

Lng (Float)
A WGS-84 longitude, in degrees

results (Enumerated value) An optional parameter specifying how many neighborhoods to return.

many (default): all neighborhoods containing the point.
one: the most specific and central neighborhood containing the point. i.e. ["The Financial District"] rather than ["The Financial District", "Downtown", "The Embarcadero"], or ["Bernal Heights North"] instead of ["Bernal Heights North","Bernal Heights"].

Response Object: Returns a list of neighborhoods (0..n).

method getNearestNeighborhood

Returns the neighborhood whose centroid is nearest to the requested latitude and longitude within a 20 linear mile range.

Request Parameters

Lat (Float)
A WGS-84 latitude, in degrees

Lng (Float)
A WGS-84 longitude, in degrees

Response Object: Returns a list containing zero to one neighborhoods. The standard neighborhood object also contains an additional distance property, describing the distance from query coordinate to the neighborhood's centroid in meters.

method getNeighborhoodsByExtent [Premium API]

Returns a list of neighborhoods within a bounding box extent defined by southwestern and northeastern corners. Note query extents covering more than 45 square miles will be rejected.

Request Parameters

swlat (Float)
A WGS-84 latitude, in degrees, of the southwest corner

swlng (Float)
A WGS-84 longitude, in degrees, of the southwest corner

nelat (Float)
A WGS-84 latitude, in degrees, of the northeast corner

nelng (Float)
A WGS-84 longitude, in degrees, of the northeast corner

Response Object: Returns a list of neighborhoods.

method getNeighborhoodsByAddress [Premium API]

This method first geocodes the input address, then returns the geocode and lists neighborhoods containing the point in a single response. This is technically executed in a single request, but for the purposes of account administration a single invocation is counted as two calls.

street (String)

city (String)

state (String)

province (String)

Response Object: If the address is unambiguous, the result will contain:

geocode (Geocode)
The geocode response information

neighborhoods (List of Neighborhoods)
Neighborhood(s)

If the address does not geocode correctly, the result will contain:

err (String)
Message indicating the type of geocode error

geocode_matches (List of Geocodes)
A list of Geocode matches, if any were returned

Searching by Administrative Boundary

These methods return lists of neighborhoods either contain or intersect the administrative boundary.

method getNeighborhoodsByCityStateCountry [Premium API]

Returns a list of neighborhood for the requested city.

city (String)
The canonical name of a city, i.e. "San Francisco"

state (Two (2) character state abbreviation)
State abbreviation, i.e. "CA"

province (Two (2) character state abbreviation) Interchangeable with the "state" parameter. Specify one of the two.

country (Three (3) character country abbreviation) The ISO 3166-1 abbreviation for the country, i.e. "USA", "CAN", etc.

Response Object: Returns a list of neighborhoods.

method getNeighborhoodsByPostalCode [Premium API]

Returns a list of neighborhoods whose areas intersect that of the requested postal code.

Request Parameters

postalcode (String) US: 5 digit ZIP / Canada: 3 digit FSU

Response Object: Returns a list of neighborhoods.

Searching by Name

Applications accepting user or other forms of input can search by name to determine the geographic location being described. Note that many neighborhoods are ambiguous. For example, many cities have neighborhoods such as “Downtown”, “Chinatown”, and “Little Italy.” In these cases, the information associated with the results can be used for disambiguation.

method getNeighborhoodsByName

Returns a list of neighborhoods for the requested neighborhood name.

Request Parameters

name (String) A neighborhood name

Response Object:: Returns a list of neighborhoods.

Getting Additional Detail

All of the methods described above return neighborhood information with associated IDs. For each neighborhood, additional information can be extracted if necessary.

method getNeighborhoodDetail

Returns neighborhood details for the requested neighborhood ID.

Request Parameters

neighborhoodId (Long Integer) A neighborhood ID

Response Object

name (String) Name of the neighborhood

city (String) City the neighborhood is predominantly contained by.

state (Two (2) character string) State the neighborhood is predominantly contained by.

postalcodes (String Array) Zipcode tabulation areas (ZCTA) the neighborhood overlaps.

alternate_names (Alternate Name Array) A list of alternate names E.g. “SoHo” is an alternate name for “South of Houston” in New York City.

wkt_centroid (String) The centroid of the neighborhood as a WKT formatted string.

lat (Float) Latitude of neighborhood centroid.

lng (Float) Longitude of neighborhood centroid.

id (Long Integer) The id of the neighborhood.

method getNeighborhoodRelationships [Premium API]

Returns neighborhood relationship attributes for the requested neighborhood ID.

Request Parameters

neighborhoodId (Long Integer) A neighborhood ID

Response Object

relation (String) Type of relationship

other_neighborhood_id (Long Integer) ID of the related neighborhood

Response Data Structures

Neighborhood

name (String) Name of the neighborhood.

city (String) City the neighborhood is predominantly contained by.

state (Two (2) character string) State the neighborhood is predominantly contained by.

id (Long Integer) The id of the neighborhood.

Geocode

SourceId (String) Pool used for the geocode

LatLng (LatLng) Latitude and Longitude of the geocode

AdminArea1 (String) Country Code

AdminArea2 (String)

AdminArea3 (String) Typically a state or province

AdminArea4 (String)

AdminArea5 (String) Typically a city center

PostalCode

ResultCode Code describing the granularity of the match

Street Number and street name of address

Sample Output

The examples below provide example HTTP requests and the HTTP response. You may test these by copying the request, and substituting your own API key.


HTTP GET getNeighborhoodsByLatLng request:
http://api0.urbanmapping.com/neighborhoods/rest/getNeighborhoodsByLatLng?lat=37.76&lng=-122.46&format=json&apikey=ABCDEFG

HTTP Response:
[
  {"city":"San Francisco","state":"CA","country":"USA","id":14466515,"name":"Twin Peaks West"},
  {"city":"San Francisco","state":"CA","country":"USA","id":13991432,"name":"Forest Knolls"}
]

HTTP GET getNearestNeighborhood request (with format=xml parameter):
http://api0.urbanmapping.com/neighborhoods/rest/getNearestNeighborhood?lat=37.76&lng=-122.46&format=xml&apikey=ABCDEFG

HTTP Response: 
<?xml version="1.0" ?>
<result>
  <neighborhoods>
    <neighborhood>
      <city>San Francisco</city>
      <state>CA</state>
      <country>USA</country>
      <id>13991432</id>
      <name>Forest Knolls</name>
    </neighborhood>
  </neighborhoods>
</result>

HTTP GET getNeighborhoodDetail request (with an output variable name specified):
http://api0.urbanmapping.com/neighborhoods/rest/getNeighborhoodDetail?neighborhoodId=13991432&outvar=my_var&apikey=ABCDEFG

HTTP Response: 
my_var = {"city":"San Francisco",
   "name":"Forest Knolls",
   "wkt_centroid":"POINT(-122.458479138591 37.7568016625813)",
   "alternate_names":[],
   "postalcodes":["94131"],
   "state":"CA",
   "lat":37.756802,
   "lng":-122.458479,
   "id":13991432
   }

HTTP GET getNeighborhoodRelationships request:
http://api1.urbanmapping.com/neighborhoods/rest/getNeighborhoodRelationships?neighborhoodId=7056&format=xml&apikey=ABCDEFG

HTTP Response:
<?xml version="1.0" ?>
<relationships>
  <relationship>
    <other_neighborhood_id>
      7041
    </other_neighborhood_id>
    <relation>
      dominates
    </relation>
  </relationship>
</relationships>

version 61 as of 2 months ago by urbanmapping Admin

Comments

Please sign in to post a comment.

Docs Navigation

Product Documentation (API)
- Neighborhoods API Overview
  - Neighborhoods REST API Reference
  - Neighborhoods SOAP API Reference
- Mass Transit API Overview

Jobs