Forward Geocode

Geocoding is the process of matching an address or other text to its corresponding geographic coordinates.

Search the world

In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do this, build a query where the text parameter is set to the item you want to find.

For example, if you want to find a YMCA facility, here's what you'd need to append to the base URL of the service.

Note the parameter values are set as follows:

parameter	value
token	*string
text	YMCA

In the example above, you will find the name of each matched locations in a property named 'label'. The top 10 labels returned at the time of writing were:

• YMCA, Bargoed Community, United Kingdom
• YMCA, Nunspeet, Gelderland
• YMCA, Belleville, IL
• YMCA, Forest City, IA
• YMCA, Fargo, ND
• YMCA, Taipei, Taipei City
• YMCA, Orpington, Greater London
• YMCA, Frisco, TX
• YMCA, Jefferson, OH
• YMCA, Belleville, IL

Spelling matters, but not capitalization. You can type ymca, YMCA, or even yMcA. See for yourself by comparing the results of the earlier search to the following:

/forward-geocode/?token=YOUR_TOKEN&text=ymcA

Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.

Set the number of results returned

By default, returns up to 10 results. If you want a different number, set the size parameter to the desired number. This example shows returning only the first result.

parameter	value
token	*string
text	YMCA
size	1

If you want 25 results, you can build the query where size is 25.

Narrow your search

If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. we supports three types: country, rectangle, and circle.

Sometimes your work might require that all the search results be from a particular country or a list of countries. To do this, you can set the boundary.country parameter value to a comma separated list of alpha-2 or alpha-3 ISO-3166 country code.

Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this:

/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.country=GBR

parameter	value
token	*string
text	YMCA
boundary.country	GBR

Note that all the results are within Great Britain:

• YMCA, Bargoed Community, United Kingdom
• YMCA, Orpington, Greater London
• YMCA, Erdington, West Midlands
• YMCA, Malvern CP, United Kingdom
• YMCA, Ancoats, Greater Manchester
• YMCA, Carmarthen Community, United Kingdom
• YMCA, Halebank, Cheshire
• YMCA, Brightlingsea CP, United Kingdom
• YMCA, Lenton Abbey, Nottinghamshire
• YMCA, Old Clee, Lincolnshire

If you try the same search request with different country codes, the results change to show YMCA locations within this region.

Results in the United States:

• YMCA, Belleville, IL
• YMCA, Forest City, IA
• YMCA, Fargo, ND
• YMCA, Frisco, TX
• YMCA, Jefferson, OH
• YMCA, Belleville, IL
• YMCA, Chapel Hill, NC
• YMCA, West Lampeter, PA
• YMCA, Bremerton, WA
• YMCA, Westerly, RI

Search within a rectangular region

To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude).

For example, to find a YMCA within the state of Texas, you can set the boundary.rect.* parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5

[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51]

parameter	value
token	*string
text	YMCA
boundary.rect.min_lat	25.84
boundary.rect.min_lon	-106.65
boundary.rect.max_lat	36.5
boundary.rect.max_lon	-93.51

• YMCA, Austin, TX
• YMCA, Frisco, TX
• Y.M.C.A, Fort Worth, TX
• YMCA, Rockwall, TX
• YMCA, Missouri City, TX
• YMCA, Northshore, TX
• YMCA, Austin, TX
• YMCA, Tulsa, OK
• YMCA, Los Alamos, NM
• YMCA, Tulsa, OK

Search within a circular region

Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located.

In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the boundary.circle.* parameter group, where boundary.circle.lat and boundary.circle.lon is your location in Ontario and boundary.circle.radius is the acceptable distance from that location. Note that the boundary.circle.radius parameter is always specified in kilometers.

[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&boundary.circle.lat=43.818156&boundary.circle.lon=-79.186484&boundary.circle.radius=35]

parameter	value
token	*string
text	YMCA
boundary.circle.lat	43.818156
boundary.circle.lon	-79.186484
boundary.circle.radius	35

You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius:

• YMCA, Toronto, Ontario
• YMCA, Markham, Ontario
• YMCA, Toronto, Ontario
• Metro Central YMCA, Toronto, Ontario
• Pinnacle Jr YMCA, Toronto, Ontario
• Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario

Search within a parent administrative area

forward-geocode has a powerful understanding of relationships between places. In particular, it has a concept called the administrative hierarchy: each record in our map is listed as belonging to a parent neighbourhood, city, region, country, and other regions. This has many uses, including filtering. The map global id (gid) of any record can be used with the boundary.gid filter to return only records with a given parent.

For example, finding YMCAs in Oklahoma with only a bounding box would be challenging: the bounding box would include much of nearby Texas, possibly leading to incorrect results.

With boundary.gid, this query can return accurate results.

/v1/search?text=YMCA&boundary.gid=whosonfirst:region:85688585

• YMCA, Stillwater, OK, USA
• YMCA, Edmond, OK, USA
• YMCA, Guymon, OK, USA
• YMCA, Grove, OK, USA
• YMCA, Midwest City, OK, USA
• YMCA, Shawnee, OK, USA
• YMCA, Owasso, OK, USA
• YMCA, Tulsa, OK, USA
• YMCA, The Village, OK, USA
• YMCA, Broken Arrow, OK, USA

By specifying a focus.point, results will be sorted in part by their proximity to the given coordinate. All else being equal, results closest to the point will show up higher. However, unlike a boundary.circle query, important results far from the given coordinate may still be returned. This allows.

To find YMCAs again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use focus.point.

[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281]

parameter	value
token	*string
text	YMCA
focus.point.lat	-33.856680
focus.point.lon	151.215281

Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, we can compute distance from that point for each resulting feature.

• YMCA, Redfern, New South Wales [distance: 3.836]
• YMCA, St Ives (NSW), New South Wales [distance: 14.844]
• YMCA, Epping (NSW), New South Wales [distance: 16.583]
• YMCA, Revesby, New South Wales [distance: 21.335]
• YMCA, Kochâang, South Gyeongsang [distance: 8071.436]
• YMCA, Center, IN [distance: 14882.675]
• YMCA, Lake Villa, IL [distance: 14847.667]
• YMCA, Onondaga, NY [distance: 15818.08]
• YMCA, 's-Gravenhage, Zuid-Holland [distance: 16688.292]
• YMCA, Loughborough, United Kingdom [distance: 16978.367]

Prioritize around a point

parameter	value
token	*string
text	YMCA
focus.point.lat	-33.856680
focus.point.lon	151.215281
boundary.country	AUS

The results below look different from the ones you saw before with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the top of the list, which is helped by the focus parameter.

• YMCA, Redfern, New South Wales [distance: 3.836]
• YMCA, St Ives (NSW), New South Wales [distance: 14.844]
• YMCA, Epping (NSW), New South Wales [distance: 16.583]
• YMCA, Revesby, New South Wales [distance: 21.335]
• YMCA, Larrakeyah, Northern Territory [distance: 3144.296]
• YMCA, Kepnock, Queensland [distance: 1001.657]
• YMCA, Kings Meadows, Tasmania [distance: 917.144]
• YMCA, Katherine East, Northern Territory [distance: 2873.376]
• YMCA, Sadadeen, Northern Territory [distance: 2026.731]
• YMCA, Ararat, Victoria [distance: 841.022]

Prioritize within a circular region

parameter	value
token	*string
text	YMCA
focus.point.lat	-33.856680
focus.point.lon	151.215281
boundary.circle.lat	-33.856680
boundary.circle.lon	151.215281
boundary.circle.radius	50

Looking at these results, they are all less than 50 kilometers away from the focus point:

• YMCA, Redfern, New South Wales [distance: 3.836]
• YMCA, St Ives (NSW), New South Wales [distance: 14.844]
• YMCA, Epping (NSW), New South Wales [distance: 16.583]
• YMCA, Revesby, New South Wales [distance: 21.335]
• Caringbah YMCA, Caringbah, New South Wales [distance: 22.543]
• YMCA building, Loftus, New South Wales [distance: 25.756]

Filter by data source

The search examples so far have returned a mix of results from all the data sources available to Pelias. Here are the sources being searched:

source	name	short name
OpenStreetMap	openstreetmap	osm
OpenAddresses	openaddresses	oa
Who's on First	whosonfirst	wof
GeoNames	geonames	gn

parameter	value
token	*string
text	YMCA
sources	oa

Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find:

• 20 Ymca Drive, Niagara, ON, Canada
• 341 Ymca Rd, New Hope, AL, USA
• 318 Ymca Rd, New Hope, AL, USA
• 138 Ymca Rd, New Hope, AL, USA
• 304 Ymca Rd, New Hope, AL, USA
• 1919 Ymca Lane, Minnetonka, MN, USA
• 101 Ymca Dr, Kannapolis, NC, USA
• 2121 Ymca Camp Road, Stokes County, NC, USA
• 1110 Ymca Camp Road, Stokes County, NC, USA
• 1581 Ymca Camp Road, Stokes County, NC, USA

Filters by data type

Here's a list of the types of places you could find in the results, sorted by granularity:

layer	description
venue	points of interest, businesses, things with walls
address	places with a street address
street	streets,roads,highways
neighbourhood	social communities, neighbourhoods
borough	a local administrative boundary, currently only used for New York City
localadmin	local administrative boundaries
locality	towns, hamlets, cities
county	official governmental area; usually bigger than a locality, almost always smaller than a region
macrocounty	a related group of counties. Mostly in Europe.
region	states and provinces
macroregion	a related group of regions. Mostly in Europe
country	places that issue passports, nations, nation-states
coarse	alias for simultaneously using all administrative layers (everything except venue and address)
[/forward-geocode/?token=YOUR_TOKEN&text=YMCA&layers=street,venue]

Available search parameters

Parameter	Type	Required	Default	Example
token	*string	yes	---	---
text	string	yes	none	Union Square
focus.point.lat	floating point number	no	none	48.581755
focus.point.lon	floating point number	no	none	7.745843
boundary.rect.min_lon	floating point number	no	none	139.2794
boundary.rect.max_lon	floating point number	no	none	140.1471
boundary.rect.min_lat	floating point number	no	none	35.53308
boundary.rect.max_lat	floating point number	no	none	35.81346
boundary.circle.lat	floating point number	no	none	43.818156
boundary.circle.lon	floating point number	no	none	-79.186484
boundary.circle.radius	floating point number	no	50	35
boundary.gid	Pelias gid	no	none	whosonfirst:locality:101748355
sources	string	no	all sources: osm,oa,gn,wof	openstreetmap,wof
layers	string	no	all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse,postalcode	address,venue
boundary.country	string	no	none	GBR,FRA
size	integer	no	10	20