find

The find operation geocodes one location per request; the input address is specified in a single parameter.

find address

NoteNote:

The World Geocoding Service offers the following two operations that allow you to geocode one location at a time:

  • find—Pass the input location as a single line of text.

    Example: text=380 New York Street, Redlands, CA 92373

  • findAddressCandidates
    • Parse the input location into multiple parameters.

      Example: Address=380 New York Street&City=Redlands&Region=CA&Postal=92373

    • Pass the input location as a single line of text.

      Example: singleLine=380 New York Street, Redlands, CA 92373

The recommended operation to use is findAddressCandidates. Single field input is easier because the address parsing is done for you; however, multifield input may provide faster responses and more precise results.

The find operation supports finding the following types of locations:

Request URL

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?<PARAMETERS>

There are several options for refining or restricting search results, including the following:

Request parameters

The find operation parameters are listed in the subsections that follow.

Required parameters

text

Specifies the location to be geocoded. This can be a street address, place name, postal code, or POI.

NoteNote:

The text parameter is not required if the category parameter is included in the request with a valid value.

Example:
text=380 New York St, Redlands, California 92373

f

The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter. This is a required parameter.

Example:
f=pjson

Optional parameters

magicKey

The find operation retrieves results quicker when you pass in valid text and magicKey values than when you don't pass in magicKey. However, to get these advantages, you need to make a prior request to suggest, which provides a magicKey. This may or may not be relevant to your workflow.

The suggest operation is often called on to improve the user experience of search boxes by analyzing partial text and providing complete names of places, addresses, POIs, and so on. For instance, typing Mbu into a search box offers Mbuji-Mayi, Democratic Republic of the Congo as a suggestion, so the user doesn't need to type the complete name.

Looking at the suggestion process from another perspective, as the user types, the suggest operation performs a text search, which is a redundant part of the overall search that the find operation can also perform. The user chooses a place or category name—narrowing the results to a specific record. The results from suggest include text and magicKey values that contain the information the user chose; passing these values from suggest into find results in faster and more accurate find operations.

In summary, using the magicKey parameter in find is a two-step process:

  • Make a request to suggest. The response includes text and magicKey properties.
  • Make a request to find and pass in the text and magicKey values returned from suggest.

NoteNote:

For best results, when the searchExtent or location/distance parameter is included in a suggest request, the same values should be included with the searchExtent or location/distance parameter in the corresponding find request.

Example:
magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

sourceCountry

This is a value representing the country. Providing this value increases geocoding speed.

Acceptable values include the full country name in English or the official language of the country, the ISO 3166-1 2-digit country code, or the ISO 3166-1 3-digit country code.

A list of supported countries and codes is available here.

Example:
sourceCountry=USA

bbox

A set of bounding box coordinates that limit the search area to a specific region. This is especially useful for applications in which a user will search for places and addresses only within the current map extent.

You can specify the spatial reference of the bbox coordinates, which is necessary if the map spatial reference is different than that of the geocoding service. Otherwise the spatial reference of the coordinates is assumed to be the same as that of the geocoding service.

The input can either be a comma-separated list of coordinates defining the bounding box or a JSON envelope object. The spatial reference of the bounding box coordinates can be included if an envelope object is used. If comma-separated values are used, they must be in the following format: Xmin,Ymin,Xmax,Ymax.

Example without a spatial reference:
bbox=-104,35.6,-94.32,41
JSON example with a spatial reference:
bbox=
{
    "xmin": -13052769,
    "ymin": 3951172,
    "xmax": -13019630,
    "ymax": 3978490,
    "spatialReference": {
        "wkid": 3395
    }
}

location

This defines an origin point location that is used with the distance parameter to sort geocoding candidates based on their proximity to the location. The distance parameter specifies the radial distance from the location in meters. The priority of candidates within this radius is boosted relative to those outside the radius.

This is useful in mobile applications where a user searches for places in the vicinity of their current GPS location; the location and distance parameters can be used in this scenario.

The location parameter can be specified without specifying a distance. If a distance is not specified, it defaults to 2000 meters.

The location can be represented with a simple comma-separated syntax (x,y), or as a JSON point object. If the comma-separated syntax is used, the spatial reference of the coordinates must be WGS84. Otherwise, the spatial reference of the point coordinates can be defined in the JSON object.

Example using simple syntax (WGS84)
location=-117.196,34.056
JSON example with a spatial reference:
location=
{
    "x": -13046165.572,
    "y": 4036389.847,
    "spatialReference": {
        "wkid": 102100
    }
}

distance

This specifies the radius of an area around a point location that is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. The distance value is in meters.

If the distance parameter is specified, the location parameter must be specified as well.

It is important to note that unlike the bbox parameter, the location/distance parameters allow searches to extend beyond the specified search radius. They are not used to filter results, but rather to rank resulting candidates based on their distance from a location. You must pass a bbox value in addition to location/distance if you want to confine the search results to a specific area.

Example of searching within 2 miles of current location:
distance=3218.69

outSR

This is the spatial reference of the x/y coordinates returned by a geocode request. This is useful for applications using a map with a spatial reference different than that of the geocode service.

The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If the parameter is not specified, the spatial reference of the output locations is the same as that of the service. The World Geocoding Service spatial reference is WGS84 (WKID = 4326).

For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.

Example (102100 is the WKID for the Web Mercator projection):
outSR=102100

category

This is a place or address type that can be used to filter find results. The category parameter supports input of single category values or multiple comma-separated values. The category parameter can be passed in a request with or without the text parameter. See the help topic Category filtering for complete details about the category parameter.

Example of category filtering with a single category:
category=Address
Example of category filtering with multiple categories:
category=Address,Postal

outFields

This is the list of fields to be returned in the response. Descriptions for each of these fields are available in the Output fields section of this documentation.

The returned address, x/y coordinates of the match location, match score, spatial reference, extent of the output feature, and the addr_type (match level) are returned by default.

Example that returns all output fields:
outFields=*
Example that returns the specified fields only:
outFields=AddrNum,StName,City

maxLocations

This is the maximum number of locations to be returned by a search, up to the maximum number allowed by the service. If not specified, one location will be returned.

The World Geocoding Service allows up to 20 candidates to be returned for a single request. Note that up to 50 POI candidates can be returned.

Example:
maxLocations=10

forStorage

This specifies whether the results of the operation will be persisted. The default value is false, which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map for instance. If you store the results in a database, for example, you need to set this parameter to true.

Applications are contractually prohibited from storing the results of geocoding transactions unless they make the request by passing the forStorage parameter with a value of true and the token parameter with a valid ArcGIS Online token. Instructions for composing a request with a valid token are provided in the Authentication topic.

ArcGIS Online service credits are deducted from the organization account for each geocode transaction that includes the forStorage parameter with a value of true and a valid token. See the ArcGIS Online service credits overview page for more information on how credits are charged.

To learn more about free and paid geocoding operations, see this help topic.

Example:
forStorage=true

Search for street addresses

You can search for a street address, street name, or street intersection using the Find method. For best results, you should include as much location information as possible in the search in addition to the street address. See the Match accuracy section for more information about obtaining optimal results for address searches.

In the following example, the complete street address, including house number, street name, city, state, and postal code, is passed as the value for the text parameter.

Example: Find a single field street address (380 New York Street, Redlands, CA 92373)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=380+New+York+Street%2C+Redlands%2C+CA+92373&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "380 New York St, Redlands, California, 92373",
   "extent": {
    "xmin": -117.19666700000001,
    "ymin": 34.055489999999999,
    "xmax": -117.194667,
    "ymax": 34.057490000000001
   },
   "feature": {
    "geometry": {
     "x": -117.19566588327319,
     "y": 34.056490200763221
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "PointAddress"
    }
   }
  }
 ]
}

The following example shows how to search for a street intersection. An intersection is where two streets cross each other, and an intersection search consists of the intersecting street names plus the containing administrative division and optional postal code. For example, "redlands blvd and new york st 92373" is a valid intersection search, as is "redlands blvd & new york st redlands ca".

NoteNote:

The valid intersection connectors can be ascertained by querying the IntersectionConnectors property from the service info URL: http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson.

Example: Find a street intersection (redlands blvd & new york st redlands ca)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=redlands+blvd+%26+new+york+st+redlands+ca&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "W Redlands Blvd & New York St, Redlands, California, 92373",
   "extent": {
    "xmin": -117.19570899999999,
    "ymin": 34.059491000000001,
    "xmax": -117.19570899999999,
    "ymax": 34.059491000000001
   },
   "feature": {
    "geometry": {
     "x": -117.19570839692426,
     "y": 34.059490820246253
    },
    "attributes": {
     "Score": 96.469999999999999,
     "Addr_Type": "StreetInt"
    }
   }
  }
 ]
}

Search for POIs

In the context of the World Geocoding Service, a POI is a point location that can represent a cultural or geographic landmark, business, or administrative division. For example, you can find amusement parks, museums, schools, restaurants, hotels, gas stations, or other types of businesses or landmarks; geographic features, such as mountains, lakes, rivers, or deserts; and administrative places, such as neighborhoods, cities, states, counties, or countries. The find operation supports geocoding POIs by name or by type.

NoteNote:

The supported types are listed in this table.

In general, valid POI search strings (the input value for the text parameter) can be formatted in variations of the following two basic structures:

Where:

Examples of valid POI search strings include the following:

It's important to note that instead of providing a zone, you can also limit searches to a specific region by defining a search extent with the bbox parameter. You can also influence the sorting of match candidates according to their proximity to a location with the location and distance parameters.

As with address searches, the quality of results depends on the amount and quality of information in the search string. If you search for "hotels" with no qualifying information such as zone, search extent, or location, your results will not be meaningful. Adding additional information to the search string, the more specific the better, will result in more accurate and relevant matches.

NoteNote:

There may be instances when searches yield unexpected results. For example, a search for "New York pizza", where the expected results are pizzerias in New York City, may instead return a match to a restaurant named "New York Pizza" in Sacramento, California. If this occurs, you can obtain the desired results by passing in the location, distance, or bbox parameter to narrow the results geographically, or you can modify the search string to "pizza in New York" or something similar.

NoteNote:

The address, phone number, and website URL of a POI can be returned by including outFields=Place_addr,Phone,URL in the request. Note that not all POIs have address, phone, and URL values associated with them. See Service output for more information about these output fields.

Example: Find a place name (Sydney AUS Starbucks)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=sydney+aus+starbucks&outFields=type%2Ccity%2Cregion&maxLocations=20&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Starbucks-Westfield Mt Druitt",
   "extent": {
    "xmin": 150.81260599999999,
    "ymin": -33.770817999999998,
    "xmax": 150.82260600000001,
    "ymax": -33.760818
   },
   "feature": {
    "geometry": {
     "x": 150.81760570500057,
     "y": -33.765816890999588
    },
    "attributes": {
     "type": "Coffee Shop",
     "city": "Sydney",
     "region": "New South Wales"
    }
   }
  },

Example: Find a business type (hotels in Miami FL)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=hotels+in+miami+FL&outFields=Type%2CCity%2CRegion&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Miccosukee Resort & Gaming",
   "extent": {
    "xmin": -80.486588999999995,
    "ymin": 25.758787999999999,
    "xmax": -80.476589000000004,
    "ymax": 25.768788000000001
   },
   "feature": {
    "geometry": {
     "x": -80.481588296999632,
     "y": 25.763788078000459
    },
    "attributes": {
     "Type": "Hotel",
     "City": "Miami",
     "Region": "Florida"
    }
   }
  }
 ]
}

Search for administrative place names

The Find method supports single field searches for administrative place names. This includes searches for neighborhoods, cities, counties, states, provinces, countries, or any combination thereof. If a search for a city name results in multiple candidates with the same name, the geocode service will sort the candidates in order of their relative importance to each other (as indicated by the value of the Rank output field), with priority generally based on population and capital status. For example, there are many cities in the world named London, so a search for "London" results in several matching candidates; London, UK will always be the top candidate since it has the greatest population.

Example: Find a single field place name (London)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=london&maxLocations=2&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "London, England, United Kingdom",
   "extent": {
    "xmin": -0.15373999999999999,
    "ymin": 51.480528,
    "xmax": -0.097739999999999994,
    "ymax": 51.536527999999997
   },
   "feature": {
    "geometry": {
     "x": -0.12573890399954735,
     "y": 51.508528044000457
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "POI"
    }
   }
  },
  {
   "name": "London, Ontario, Canada",
   "extent": {
    "xmin": -81.325040999999999,
    "ymin": 42.891387000000002,
    "xmax": -81.141041000000001,
    "ymax": 43.075386999999999
   },
   "feature": {
    "geometry": {
     "x": -81.233039613999665,
     "y": 42.983386547000464
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "POI"
    }
   }
  }
 ]
}

However, rank alone is not always enough to distinguish between administrative places. Additionally, you may not necessarily want to find the highest-ranked feature for a particular search. It may be necessary to remove ambiguity by refining searches with additional information. For example, a search for "Oxford" returns Oxford, UK, as the top candidate based on rank. If you instead want to find the town of Oxford, Alabama, it is necessary to add the state information to the search.

Example: Search for city, state (Oxford, AL)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=oxford%2C+al&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Oxford, Alabama, United States",
   "extent": {
    "xmin": -85.902957999999998,
    "ymin": 33.546267999999998,
    "xmax": -85.766958000000002,
    "ymax": 33.682268000000001
   },
   "feature": {
    "geometry": {
     "x": -85.834956749999662,
     "y": 33.614268443000469
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "POI"
    }
   }
  }
 ]
}

Search for postal codes

The Find method supports searches for postal codes and postal code extensions. When searching for postal codes it is important to note that the same code can be valid in more than one country; for best results it may be necessary to include additional information with the postal code, such as city or country.

Example: Find a postal code (20002 USA)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=20002+USA&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "20002, Washington, District Of Columbia",
   "extent": {
    "xmin": -76.994172000000006,
    "ymin": 38.902411000000001,
    "xmax": -76.984172000000001,
    "ymax": 38.912410999999999
   },
   "feature": {
    "geometry": {
     "x": -76.989170693771712,
     "y": 38.907411026698639
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "Postal"
    }
   }
  }
 ]
}

Search for x/y coordinates

The geocode service supports searches for x/y coordinate pairs as well. The output is a geometry point with a match address that is the same as the input coordinates. This is different than reverse geocoding, in which input x/y coordinates are resolved to a matching street address. See Reverse geocoding for more information.

NoteNote:

The only valid input format for coordinate searches is text=<x-coordinate,y-coordinate>, where the spatial reference of the coordinates is WGS84.

Example: Find an x/y coordinate pair (-115.172783,36.114789)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=-115.172783%2C36.114789&outFields=addr_type&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "-115.172783 36.114789",
   "extent": {
    "xmin": -115.172783,
    "ymin": 36.114789000000002,
    "xmax": -115.172783,
    "ymax": 36.114789000000002
   },
   "feature": {
    "geometry": {
     "x": -115.172783,
     "y": 36.114789000000002
    },
    "attributes": {
     "addr_type": "LatLong"
    }
   }
  }
 ]
}

Specify output fields

The Find method allows you to specify individual output fields or return all output fields. The outFields parameter is used for this. If you want to return all supported output fields, set outFields=*; if you only want to return the default output fields, outFields does not need to be passed in the request. If you want to return specific fields, pass the desired field names as comma-separated values, such as outFields=PlaceName,Type,City,Country, which returns the name, feature type, city, and country for a POI search.

See Output fields for detailed information about the fields returned by a Find request.

Example: Specify individual outfields for a POI search (PlaceName,Type,City,Country)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=coffee+shops+in+austin&outFields=PlaceName%2CType%2CCity%2CCountry&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Starbucks",
   "extent": {
    "xmin": -97.973419000000007,
    "ymin": 30.336169000000002,
    "xmax": -97.963419000000002,
    "ymax": 30.346169
   },
   "feature": {
    "geometry": {
     "x": -97.968418052999652,
     "y": 30.34116889100045
    },
    "attributes": {
     "PlaceName": "Starbucks",
     "Type": "Coffee Shop",
     "City": "Austin",
     "Country": "USA"
    }
   }
  }
 ]
}

Specify the output spatial reference

By default, the World Geocoding Service returns candidate geometry in WGS84 coordinates (decimal degrees). You can specify a different spatial reference for output coordinates by using the outSR parameter. This is necessary if you have a mapping application in which you display geocoding candidates, and the map spatial reference is not WGS84. For example, the ArcGIS.com basemaps use a Web Mercator spatial reference, with coordinates in meters. To display geocoding candidates correctly in such a map you would need to set outSR=102100, which is the WKID of the Web Mercator spatial reference.

For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.

Example: Specify output coordinates in Web Mercator spatial reference (380 new york st redlands ca)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=380+new+york+st+redlands+ca&outSR=102100&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 102100,
  "latestWkid": 3857
 },
 "locations": [
  {
   "name": "380 New York St, Redlands, California, 92373",
   "extent": {
    "xmin": -13046273.293108851,
    "ymin": 4036255.4132860568,
    "xmax": -13046050.654127261,
    "ymax": 4036524.1432637926
   },
   "feature": {
    "geometry": {
     "x": -13046161.849304594,
     "y": 4036389.8044578899
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "PointAddress"
    }
   }
  }
 ]
}

Specify the maximum number of candidates

The maxLocations parameter allows you to specify the maximum number of candidates to be returned by a search, up to the maximum number of candidates allowed by the World Geocoding Service. By default, the service allows up to 20 candidates to be returned for address searches and 50 for POI searches. As an example, if you set maxLocations=10, Find will return the top 10 candidates for the search, regardless of whether the search matches to an address or a POI. If no value is specified for maxLocations, Find only returns a single candidate.

Example: Specify the maximum number of candidates for a POI search (Starbucks in Paris)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=starbucks+in+paris&outFields=PlaceName%2CCity%2CCountry&maxLocations=2&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Starbucks",
   "extent": {
    "xmin": 2.274289,
    "ymin": 48.851688000000003,
    "xmax": 2.2842889999999998,
    "ymax": 48.861688000000001
   },
   "feature": {
    "geometry": {
     "x": 2.2792886790004445,
     "y": 48.856688363000501
    },
    "attributes": {
     "PlaceName": "Starbucks",
     "City": "Paris",
     "Country": "FRA"
    }
   }
  },
  {
   "name": "Starbucks",
   "extent": {
    "xmin": 2.2789459999999999,
    "ymin": 48.864139000000002,
    "xmax": 2.2889460000000001,
    "ymax": 48.874139
   },
   "feature": {
    "geometry": {
     "x": 2.2839457660004427,
     "y": 48.869138758000474
    },
    "attributes": {
     "PlaceName": "Starbucks",
     "City": "Paris",
     "Country": "FRA"
    }
   }
  }
 ]
}

Search within an extent

The Find method allows spatial filtering of search results using the bbox parameter. If you want to confine a search to a localized area, something that is especially useful in mobile applications, you can define a bounding rectangle to search within. No candidates outside of the rectangle are returned. Bounding rectangle coordinates can be entered as a simple comma-separated string in the format <lower left corner>,<upper right corner>. If the simple format is used, the coordinates must be in the default spatial reference of the geocode service, which is WGS84. The bbox parameter can be used with all supported search types (street address, POI, admin place, and postal code).

The following URL shows how to find McDonald's in downtown San Diego using the simple bbox format. Note that the actual response will contain more than one McDonald's for this request.

Example: Find POIs using bbox with default spatial reference (McDonald's)

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=mcdonalds&outFields=City%2C+Type&maxLocations=20&bbox=-117.172026%2C32.706517%2C-117.152498%2C32.725514&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "McDonald's",
   "extent": {
    "xmin": -117.166079,
    "ymin": 32.709496999999999,
    "xmax": -117.15607900000001,
    "ymax": 32.719496999999997
   },
   "feature": {
    "geometry": {
     "x": -117.16107793699967,
     "y": 32.714496787000485
    },
    "attributes": {
     "City": "San Diego",
     "Type": "Burgers"
    }
   }
  },

You can specify a spatial reference for the bbox, which is necessary if your map uses a different spatial reference than the geocode service. For example, the default ArcGIS.com basemaps utilize a Web Mercator spatial reference (WKID = 102100), with coordinates in meters. The bbox must be passed as a JSON envelope object if the coordinates are in a spatial reference other than WGS84. The following request URL uses the previous example of McDonald's in downtown San Diego but specifies the bounding rectangle with Web Mercator coordinates.

NoteNote:

Note that in this example the outSR property is set to 102100 so that the output coordinates are also in Web Mercator coordinates. If outSR was left blank here the coordinates would be returned in WGS84 coordinates.

For a list of supported spatial references and their WKID values, see Projected coordinate systems and Geographic coordinate systems.

Example: Find POIs using bbox with Web Mercator spatial reference (McDonald's)

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=mcdonalds&outFields=City%2C+Type&maxLocations=20&bbox={%22xmin%22:-13043558,%22ymin%22:3856395,%22xmax%22:-13041325,%22ymax%22:3858918,%22spatialReference%22:{%22wkid%22:102100}}&outSR=102100&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 102100,
  "latestWkid": 3857
 },
 "locations": [
  {
   "name": "McDonald's",
   "extent": {
    "xmin": -13042868.252524463,
    "ymin": 3856807.7266816632,
    "xmax": -13041755.057616532,
    "ymax": 3858130.7944575814
   },
   "feature": {
    "geometry": {
     "x": -13042311.536737842,
     "y": 3857469.2138471175
    },
    "attributes": {
     "City": "San Diego",
     "Type": "Burgers"
    }
   }
  },

Searches that utilize bbox can also include zone information (city/state/country). If the extent defined for bbox is large enough to encompass multiple cities, it may be necessary to include the city name in the search to achieve optimal results. For example, if the bbox extent covers the Dallas-Fort Worth metropolitan region, and you search for "Starbucks", matching locations in Dallas or Fort Worth, or any of their suburbs, could be returned. If you specifically want to find Starbucks in Garland, this needs to be specified in the search.

Example: Find POIs using bbox and zone (starbucks garland)

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=starbucks+garland&outFields=Type%2CCity%2CRegion&maxLocations=20&bbox=-97.407282%2C32.416436%2C-96.537829%2C33.141819&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Starbucks",
   "extent": {
    "xmin": -96.672148000000007,
    "ymin": 32.954658000000002,
    "xmax": -96.662148000000002,
    "ymax": 32.964658
   },
   "feature": {
    "geometry": {
     "x": -96.667147024999679,
     "y": 32.959657532000449
    },
    "attributes": {
     "Type": "Coffee Shop",
     "City": "Garland",
     "Region": "Texas"
    }
   }
  },

You can also search for street addresses within an extent. When the bbox parameter is defined for a street address search, city and postal code can be omitted from the search, and valid matches can still be found. However, if the bbox is large, it is possible for a street address to occur multiple times within the extent, and it may be necessary to refine the search by including city, state, postal code, or other distinguishing information. Additionally, if the search includes a city or postal code that is outside the bbox, no matches will be returned. See the following example, which illustrates finding a street address using bbox.

Example: Find a street address using bbox (380 New York St)

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=380+New+York+St&bbox=-117.225635%2C34.015757%2C-117.119866%2C34.087402&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "380 New York St, Redlands, California, 92373",
   "extent": {
    "xmin": -117.19666700000001,
    "ymin": 34.055489999999999,
    "xmax": -117.194667,
    "ymax": 34.057490000000001
   },
   "feature": {
    "geometry": {
     "x": -117.19566588327319,
     "y": 34.056490200763221
    },
    "attributes": {
     "Score": 100,
     "Addr_Type": "PointAddress"
    }
   }
  }
 ]
}

Proximity searches

Geocoding results are typically sorted according to their relevance to the search and their relative importance. However, with some applications, especially mobile apps, users are more concerned with finding features closest to their current location. For this reason, the Find method additionally supports prioritization of candidates based on their distance from a specified point. By utilizing the location and distance parameters, you can define a circular area of influence for your searches. The location parameter represents the center point of the area, and the distance parameter defines the radius in meters. The purpose of this area is to boost the rank of results closest to the specified location so that they show up higher in the list of candidates. Results that are within the area receive a greater boost than those outside the area.

It is important to note that proximity search does not filter results that are outside of the location/distance area—it is intended to influence the sort order of results so that the most locationally-relevant candidates are returned first. For instance, if your location is Las Vegas, distance = 3000, and you search for "Golden Nugget", the first candidate is Golden Nugget in Las Vegas. The second is Golden Nugget in Atlantic City, New Jersey. So even though Golden Nugget in Atlantic City is much farther away than 3000 meters, it is still returned because it is the second most relevant (closest) candidate. In general, the number of candidates returned by a proximity search is only limited by the maxLocations parameter.

Example: Find a place name using proximity search (Golden Nugget)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=golden%20nugget&outFields=Type%2CCity%2CRegion%2CCountry&maxLocations=10&location=-115.172783%2C36.114789&distance=3000&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Golden Nugget",
   "extent": {
    "xmin": -115.149317,
    "ymin": 36.165798000000002,
    "xmax": -115.13931700000001,
    "ymax": 36.175798
   },
   "feature": {
    "geometry": {
     "x": -115.1443163999997,
     "y": 36.170797582000489
    },
    "attributes": {
     "Type": "Casino",
     "City": "Las Vegas",
     "Region": "Nevada",
     "Country": "USA"
    }
   }
  },
  {
   "name": "Golden Nugget",
   "extent": {
    "xmin": -88.865808999999999,
    "ymin": 30.387298000000001,
    "xmax": -88.855808999999994,
    "ymax": 30.397297999999999
   },
   "feature": {
    "geometry": {
     "x": -88.860807742999668,
     "y": 30.392297854000446
    },
    "attributes": {
     "Type": "Casino",
     "City": "Biloxi",
     "Region": "Mississippi",
     "Country": "USA"
    }
   }
  },

If you only want to return candidates within a specific area and also sort the candidates according to their proximity to a location, you need to define a search extent by passing the bbox parameter in the request along with the location and distance parameters. Consider the Golden Nugget example again. If your location is in Las Vegas and you only want to find features named Golden Nugget within your map extent, you would need to construct a request with the following parameters:

The request URL would be similar to the one below. See the Searching within an extent section for more information about the bbox parameter.

Example: Find a place name using both proximity and bbox (Golden Nugget)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=golden+nugget&outFields=Type,City,Region,Country&bbox=-115.161912,36.158764,-115.126925,36.179793&location=-115.144989,36.167361&distance=4000&forStorage=false&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Golden Nugget",
   "extent": {
    "xmin": -115.149317,
    "ymin": 36.165798000000002,
    "xmax": -115.13931700000001,
    "ymax": 36.175798
   },
   "feature": {
    "geometry": {
     "x": -115.1443163999997,
     "y": 36.170797582000489
    },
    "attributes": {
     "Type": "Casino",
     "City": "Las Vegas",
     "Region": "Nevada",
     "Country": "USA"
    }
   }
  }
 ]
}

There is different logic applied when the search text matches to many candidates, as opposed to a few. For example, when you search for Starbucks or McDonald's, for which there are potentially thousands of results, the search does not extend indefinitely beyond the distance value if exact matches are found within the distance. The results are confined to a region slightly larger than the area defined by the distance value. It is assumed that a user searching for a place such as Starbucks only wants to know where the closest Starbucks is, and is not interested in finding Starbucks in another city. As an example, if your location is in Fayetteville, North Carolina, and you want to find Starbucks within a 10000 meter distance with maxLocations = 20, five Starbucks are returned. Even though there are many more Starbucks in North Carolina, only the Starbucks nearest to the location are returned. If no exact matches are found within this region, the search is extended globally to find the most relevant match.

Example: Find POI using proximity search (Starbucks)

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=starbucks&outFields=Type%2CCity%2CRegion%2CCountry&maxLocations=20&location=-78.890096%2C35.055167&distance=10000&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Starbucks",
   "extent": {
    "xmin": -78.929659999999998,
    "ymin": 35.040519000000003,
    "xmax": -78.919659999999993,
    "ymax": 35.050519000000001
   },
   "feature": {
    "geometry": {
     "x": -78.924658954999643,
     "y": 35.045519437000451
    },
    "attributes": {
     "Type": "Coffee Shop",
     "City": "Fayetteville",
     "Region": "North Carolina",
     "Country": "USA"
    }
   }
  },
  {
   "name": "Starbucks",
   "extent": {
    "xmin": -78.940089999999998,
    "ymin": 35.033748000000003,
    "xmax": -78.930090000000007,
    "ymax": 35.043748000000001
   },
   "feature": {
    "geometry": {
     "x": -78.935089029999631,
     "y": 35.03874753800045
    },
    "attributes": {
     "Type": "Coffee Shop",
     "City": "Fayetteville",
     "Region": "North Carolina",
     "Country": "USA"
    }
   }
  },

Category filtering

The find operation supports filtering searches by category values, which represent address and place types. By including the category parameter in a find request, you can avoid false positive matches to unexpected place and address types due to ambiguous searches.

For example, a user may search for "Mammoth", expecting the service to match to Mammoth Mountain ski resort. However, there are many places in the world named "Mammoth", so the search returns several cities named "Mammoth".

Example: Search for "Mammoth" without category

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=Mammoth&category=&outFields=PlaceName%2CType%2CPlace_Addr%2CCity%2CRegion&maxLocations=5&forStorage=false&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Mammoth, Arizona, United States",
   "extent": {
    "xmin": -110.653649,
    "ymin": 32.709569000000002,
    "xmax": -110.62764900000001,
    "ymax": 32.735568999999998
   },
   "feature": {
    "geometry": {
     "x": -110.64064804599968,
     "y": 32.722569071000464
    },
    "attributes": {
     "PlaceName": "Mammoth",
     "Type": "City",
     "Place_Addr": "",
     "City": "",
     "Region": "Arizona"
    }
   }
  },
  {
   "name": "Mammoth, California, United States",
   "extent": {
    "xmin": -121.37499,
    "ymin": 41.710436999999999,
    "xmax": -121.33499,
    "ymax": 41.750436999999998
   },
   "feature": {
    "geometry": {
     "x": -121.35498927799972,
     "y": 41.730436732000499
    },
    "attributes": {
     "PlaceName": "Mammoth",
     "Type": "City",
     "Place_Addr": "",
     "City": "",
     "Region": "California"
    }
   }
  },

The solution for this case is to pass the category parameter in the request. By including category=Ski Resort in the request, all places that are not ski resorts are bypassed by the search, and only ski resorts whose names begin with "Mammoth" are returned.

Example: Search for "Mammoth" with category=Ski Resort

Request URL:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find?text=Mammoth&category=Ski+Resort&outFields=PlaceName%2CType%2CPlace_Addr%2CCity%2CRegion&maxLocations=5&forStorage=false&f=pjson

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "name": "Mammoth Mountain",
   "extent": {
    "xmin": -119.062268,
    "ymin": 37.625985999999997,
    "xmax": -119.01226800000001,
    "ymax": 37.675986000000002
   },
   "feature": {
    "geometry": {
     "x": -119.03726744799968,
     "y": 37.650986233000481
    },
    "attributes": {
     "PlaceName": "Mammoth Mountain",
     "Type": "Ski Resort",
     "Place_Addr": "1 Minaret Rd, Mammoth Lakes, California",
     "City": "Mammoth Lakes",
     "Region": "California"
    }
   }
  },

See the topic Category filtering for complete details.

7/5/2017