Batch

Batch Geocode - geocodeAddresses

You can geocode a list of many addresses using the LocateNYC API /geocodeAddresses operation. Address types include address, place, intersection, NYC building (using BIN), NYC tax lot (using BBL), street segment (the street between two consecutive intersections), street segment blockface (one side of the street), and street stretch (the stretch of street between intersections that are not consecutive). You can pass the address components in a single parameter using the search option or separtated into multiple parameters. The response is the same for both scenarios.

LocateNYC returns a wide variety of response parameters. Please see the Response Parameters sections below for a full list. Many of these parameters are derived directly for the NYC Geosupport API and are described using the descriptions provided in the Geosupport User Programming Guide (UPG). Many other parameters are created directly from the LocateNYC API and are also descirbed in Repsonse Parameters section.

---

---

Contents

•  Request URL
•  Parameters
•  geocodeAddresses Details
•  Batch geocode using single-line and multiline input
•  Response Parameters

---

Request URL

GET/POST https://locatenyc.io/arcgis/rest/services/locateNYC/v1/GeocodeServer/geocodeAddresses

---

Parameters

Required Parameters

token

(string) JSON web token (JWT). An encoded token used to authenticate the user. Can be obtained by making a request to the /tokens/generateToken operation.

Optional Parameters

addresses

(string) A record set representing the addresses to be geocoded. Each record must include an OBJECTID attribute with a unique value, as well as various address fields accepted by the corresponding geocode service. For passing in the location name as a single line of text—single field batch geocoding—use the search input field. For passing in the location name as multiple lines of text—multifield batch geocoding—use the address fields described in /findAddressCandidates.

Example:

addresses={
  "records": [
    {
      "attributes": {
        "OBJECTID": 0,
        "search": "231 East 10 Street, Manhattan"
      }
    },
    {
      "attributes": {
        "OBJECTID": 1,
        "search": "314 W 100 St, Manhattan"
      }
    },
    {
      "attributes": {
        "OBJECTID": 2,
        "compassDirection": "e",
        "onStreet": "2nd Ave",
        "crossStreetOne": "101 st",
        "crossStreetTwo": "102 st",
        "boroughCrossStreetOne": "manhattan"
      }
    },
    {
      "attributes": {
        "OBJECTID": 3,
        "houseNumber": "231",
        "street": "e 10 st",
        "borough": "manhattan"
      }
    }
  ]
}

Example: If address list is sent as a HTTP POST request, addresses must be sent in the body of the POST in the following format.

{
  "addresses": {
    "records": [
      {
        "attributes": {
          "OBJECTID": 0,
          "search": "231 East 10 Street, Manhattan"
        }
      }
    ]
  }
}

outSR

The well-known ID of the spatial reference, or a spatial reference JSON object for the returned addresses. WKID accepted include: [4326 (default, WGS), 2263 (Long Island State Plane), 3857 (Web Mercator), 102100 (Web Mercator), 26918 (UTM 18N)]. Format 1; 3857. Format 2; {"wkid":102100}.

Examples:

outSR=3857


outSR={"wkid":102100}


normalizeType

(string) The normalize type parameter represents how the address should be normalized by LocateNYC/Geosupport. For more details, please refer to the Geosupport User Guide The supported types are

• input - (default) normalizes the provided input address
• primary - normalizes to DCP primary street name
• principal - normalizes to DCP principal street name
• preferred - normalizes to DCP preferred street name
• nycps - Only supported for on-premise Enterprise install. If this value is passed using locatenyc.io, the default value of input will be used instead. For /reverseGeocode, the default is preferred and passing input will result in preferred normalized output. Only active for input will be used instead. For /reverseGeocode, street segment, street strech, and blockface requests

callback

(string) Callback parameter. Produces padded JSON response. Used by Esri APIs/SDKs. Only use this if you really know what your doing.

f

(string) Requested format of the response. Only accepts 'json', and the default value is 'json'.

---

geocodeAddresses Details

GET/POST https://locatenyc.io/arcgis/rest/services/locateNYC/v1/GeocodeServer/geocodeAddresses

Batch geocoding is a very useful operation for performing large amounts of geocodes. The LocateNYC API also integrates seamlessly with the Esri ArcGIS platform, so batch geocodes can be performed using ArcGIS Pro, ArcGIS Online, and ArcGIS Enterprise. For an example of how to do this in ArcGIS Online/Portal please see Batch Geocoding or Esri Tools for Geocoding Tables in AGO/Portal There is a limit to the maximum number of addresses that can be geocoded in a single Batch request. The limit for locatenyc.io is 150. That limit can be increased for on-premise Enterprise LocateNYC installations, where batch geocoding large batch jobs is a priority.

The batch geocode response parameters are different from the /findAddressCandidates operation. Since batch geocode accepts a variety of address types, the format and response parameters are condensed down to a smaller standardized set. Please see the examples below.

An important detail to keep in mind when architecting batch geocoding API calls is that the POST method is preferred when geocoding large amounts of addresses, since HTTP GET has a character length limit.

Batch geocode using single-line and multiline input

For the LocateNYC batch single-line format, the search parameter is used, in contrast to the typical Esri SingleLine parameter.

---

Response Parameters

Below is a list of response parameters that may be returned in the response for the address search function in LocateNYC. Most of these parameters are derived from the NYC Geosupport software. Some of the parameters are returned from LocateNYC software only.

Match_addr

Parameter Name:	Match_addr
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:
Field Status:	Active
Description:	Normalized address. Same as FullAddress. This parameter is added for Esri reverseGeocode standardization.

---

Loc_name

Parameter Name:	Loc_name
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:
Field Status:	Active
Description:	LocateNYC locator name. This is the internal locator that was used to locator the coordinates. This parameter is added for Esri reverseGeocode standardization.

---

Addr_type

Parameter Name:	Addr_type
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:
Field Status:	Active
Description:	The type of address that was returned in the reverse geocode. This will be 'PointAddress' if an address point locator was used. It will be 'StreetAddress' if an address interpolation was used. This parameter is added for Esri reverseGeocode standardization.

---

Score

Parameter Name:	Score
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:
Field Status:	Active
Description:	Match score. Indicates strength of match with 100 being the highest and 0 being the lowest (no match). This parameter is added for Esri reverseGeocode standardization

---

geoclient_function

Parameter Name:	geoclient_function
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:
Field Status:	Active
Description:	Internal LocateNYC code for geoclient function used for address matching.

---

ResultID

Parameter Name:	ResultID
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:	Numeric
Field Status:	Active
Description:	Batch geocoding ID. This should match the OBJECTID that was passed in the request.

---

Status

Parameter Name:	Status
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:	Numeric
Field Status:	Active
Description:	Batch geocoding match status. Will be an 'M' for a match, and a 'U' for an unmatched address.

---

address

Parameter Name:	address
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:	Numeric
Field Status:	Active
Description:	The normalized match address.

---

wkid

Parameter Name:	wkid
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:	Character
Field Status:	Active
Description:	This indicates the Projected Coordinate System or the Geographic Coordinate System used to locate geographic features in the map. For a list of projected coordinate systems please see https://developers.arcgis.com/rest/services-reference/projected-coordinate-systems.htm. For a list of geographic coordinate systems please see https://developers.arcgis.com/rest/services-reference/geographic-coordinate-systems.htm

---

latestWkid

Parameter Name:	latestWkid
Geosupport Parameter Name:
Geosupport Functions:
Field Length:
Field Format:	Character
Field Status:	Active
Description:	This indicates the Projected Coordinate System or the Geographic Coordinate System used to locate geographic features in the map. For a list of projected coordinate systems please see https://developers.arcgis.com/rest/services-reference/projected-coordinate-systems.htm. For a list of geographic coordinate systems please see https://developers.arcgis.com/rest/services-reference/geographic-coordinate-systems.htm. Identifies the current wkid value associated with the same spatial reference. For example a WKID of '102100' (Web Mercator) may have a latestWKid of '3857' since '102100' is deprecated.

---