URBANWARE Neighborhood API Reference

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

The API provides three types of search methods:

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

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: .

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.

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 (0..n).

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)  Two (2) character state or province abbreviation.

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

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 or province abbreviation)
State abbreviation, i.e. "CA"

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 (0..n).

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 (0..n).

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 (0..n).

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 [Premium API]

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>