If you have a list of addresses and need to find their corresponding geographical coordinates, you are in the right place. This tutorial teaches you how to run a batch geocode and get results in CSV or JSON format.
All we need to run the geocoding requests is a tool for HTTP POST requests. Everything else the API does for us!
We use the Postman to submit a JSON array for geocoding, as it's free for personal use and well known. Nevertheless, you can use any other tool you like. For example, you can send the requests with CURL as well.
Geoapify Batch Geocoding to CSV/JSON formats
Our Geocoder has a special endpoint that allows sending a list of addresses as a JSON array and retrieving address latitude, longitude coordinates, address details, like postcode, city, a country in JSON or CSV format.
You can store and utilize the JSON results in your projects. At the same time, addresses in CSV format can be easily visualized and analyzed with spreadsheet apps, like Excel, Open Office, or LibreOffice.
Send HTTP POST a Batch Geocoder Job in Postman
OK, let's start! Let's assume that we have a text file with addresses that need to be processed by a geocoder:
668 Cedar St, San Carlos, CA 94070, United States of America
545 Southwest Taylor Street, Portland, OR 97204, United States of America
1415 Southwest Park Avenue, Portland, OR 97201, United States of America
1019 Southwest Morrison Street, Portland, OR 97205, United States of America
400 Southwest 6th Avenue, Portland, OR 97204, United States of America
1972 Northwest Flanders Street, Portland, OR 97209, United States of America
1150 Northwest Quimby Street, Portland, OR 97209, United States of America
2116 Northwest 20th Avenue, Portland, OR 97209, United States of America
200 East 13th Street, Vancouver, WA 98660, United States of America
1108 Main St, Vancouver, WA 98660, United States of America
410 West Mill Plain Boulevard, Vancouver, WA 98660, United States of America
900 W Evergreen Blvd, Vancouver, WA 98660, United States of America
2008 Simpson Ave, Vancouver, WA 98660, United States of America
...If you have addresses in another format, don't worry! Most of them can be easily transformed into strings or JSON. For example, you can copy a column from Excel or another Spreadsheet and paste it to any text editor.
We will convert this list into a JSON array and send it as a request body to Batch Geocoder.
Step 1. Request URL
Here is the URL for Geoapify Batch Geocoding:
https://api.geoapify.com/v1/batch/geocode/search?apiKey=YOUR_API_KEYAll you need to do is send an array of addresses in JSON format to the URL using HTTP POST.
In addition, you can add a filter, bias, language, and/or type when searching addresses in a limited geographical area, of a particular type or when you need a localized version of an address. To find more information about the parameters, please visit the Geocoding API documentation.
Here are some examples of Batch Geocoding URLs:
- searching postcodes:
https://api.geoapify.com/v1/batch/geocode/search?type=postcode&apiKey=YOUR_API_KEY
- searching postcodes in the USA:
https://api.geoapify.com/v1/batch/geocode/search?type=postcode&filter=countrycode:us&apiKey=YOUR_API_KEY
- german versions of postcodes in the USA:
https://api.geoapify.com/v1/batch/geocode/search?type=postcode&filter=countrycode:us&lang=de&apiKey=YOUR_API_KEY
To run the batch requests, you will need a Geoapify API key. You can find information on how to generate an API key on the Getting Started page.
Step 2. Build the request body
Now we will build a body for the POST request. The API accepts a list of addresses in JSON format. If you have addresses in text format, you can easily convert them with an online tool. For instance, we used wtools.io to do that.
As another option, you can use the "Find/Replace" functionality to format strings into a JSON array.
Here is JSON array that can be used as the request body:
[
"668 Cedar St, San Carlos, CA 94070, United States of America",
"545 Southwest Taylor Street, Portland, OR 97204, United States of America",
"1415 Southwest Park Avenue, Portland, OR 97201, United States of America",
"1019 Southwest Morrison Street, Portland, OR 97205, United States of America",
"400 Southwest 6th Avenue, Portland, OR 97204, United States of America",
"1972 Northwest Flanders Street, Portland, OR 97209, United States of America",
"1150 Northwest Quimby Street, Portland, OR 97209, United States of America",
"2116 Northwest 20th Avenue, Portland, OR 97209, United States of America",
"200 East 13th Street, Vancouver, WA 98660, United States of America",
"1108 Main St, Vancouver, WA 98660, United States of America",
"410 West Mill Plain Boulevard, Vancouver, WA 98660, United States of America",
"900 W Evergreen Blvd, Vancouver, WA 98660, United States of America",
"2008 Simpson Ave, Vancouver, WA 98660, United States of America",
...
]Step 3. Send the request
To create a batch geocoding job, just press the "Send" button below. The requests will return the job ID and the results URL.
Use the URL retuned to get search results. You can just click on the URL if you use Postman to open it in a new tab:
Note it may take some time until the geocoder completed the job. The processing time may reach minutes and even hours depending on the number of addresses.
Wait some time and try to get results again when you get “pending” as the result status:
{
"id": "4e7806fc18c444f39b8d424679a7a6f1",
"status": "pending"
}Get Batch Gecoding addresses as a JSON or CSV
By default, the batch endpoint returns addresses in JSON format. In addition to result addresses and their coordinates, the API returns the original address string and parsed address:
[
{
"query": {
"text": "668 Cedar St, San Carlos, CA 94070, United States of America",
"parsed": {
"housenumber": "668",
"street": "cedar st",
"postcode": "94070",
"city": "san carlos",
"state": "ca",
"country": "united states of america",
"expected_type": "building"
}
},
"datasource": {
"sourcename": "openstreetmap",
"attribution": "© OpenStreetMap contributors",
"license": "Open Database License",
"url": "https://www.openstreetmap.org/copyright"
},
"housenumber": "668",
"street": "Cedar Street",
"suburb": "Devonshire",
"city": "San Carlos",
"county": "San Mateo County",
"state": "California",
"postcode": "94070",
"country": "United States of America",
"country_code": "us",
"lon": -122.26380104761905,
"lat": 37.502683380952384,
"formatted": "668 Cedar Street, San Carlos, CA 94070, United States of America",
"address_line1": "668 Cedar Street",
"address_line2": "San Carlos, CA 94070, United States of America",
"state_code": "CA",
"result_type": "building",
"rank": {
"importance": 1.021,
"popularity": 4.377368426402045,
"confidence": 1,
"confidence_city_level": 1,
"confidence_street_level": 1,
"confidence_building_level": 1,
"match_type": "full_match"
},
"place_id": "51290bca1de2905ec05973b7d4ed57c04240f00102f901f48dac0f00000000c00203"
},
...
]You can get addresses in CSV format by adding format=csv parameter to the resulting URL:
https://api.geoapify.com/v1/batch/geocode/search?id=JOB_ID&apiKey=YOUR_API_KEY&format=csvHere are some example results in CSV format:
"query.text","query.parsed.housenumber","query.parsed.street","query.parsed.postcode","query.parsed.city","query.parsed.state","query.parsed.country","query.parsed.expected_type","datasource.sourcename","datasource.attribution","datasource.license","datasource.url","housenumber","street","suburb","city","county","state","postcode","country","country_code","lon","lat","formatted","address_line1","address_line2","state_code","result_type","rank.importance","rank.popularity","rank.confidence","rank.confidence_city_level","rank.confidence_street_level","rank.match_type","place_id","category","name"
"668 Cedar St, San Carlos, CA 94070, United States of America","668","cedar st","94070","san carlos","ca","united states of america","building","openstreetmap","© OpenStreetMap contributors","Open Database License","https://www.openstreetmap.org/copyright","668","Cedar Street","Devonshire","San Carlos","San Mateo County","California","94070","United States of America","us","-122.26380104761905","37.502683380952384","668 Cedar Street, San Carlos, CA 94070, United States of America","668 Cedar Street","San Carlos, CA 94070, United States of America","CA","building","1.021","4.377368426402045","1","1","1","full_match","51290bca1de2905ec05973b7d4ed57c04240f00102f901f48dac0f00000000c00203","",""
"545 Southwest Taylor Street, Portland, OR 97204, United States of America","545","southwest taylor street","97204","portland","or","united states of america","building","openstreetmap","© OpenStreetMap contributors","Open Database License","https://www.openstreetmap.org/copyright","545","Southwest Taylor Street","Downtown","Portland","Multnomah County","Oregon","97204","United States of America","us","-122.6788812","45.5178857","545 Southwest Taylor Street, Portland, OR 97204, United States of America","545 Southwest Taylor Street","Portland, OR 97204, United States of America","OR","building","0.9209999999999999","6.747843008774312","1","1","1","full_match","51a2f721ca72ab5ec059754820144ac24640f00103f901ea5c1ba101000000c00203","service.financial.atm",""
...Batch geocoding service terms and cost
- With Geoapify Batch Geocoder, you can easily geocode addresses for your business or personal needs.
- We’re a geocoder that uses open data sources. You can store and redistribute the data as you see fit.
- Please keep data source attribution when storing or redistributing data.
- Geocoding of 1 address costs 0.5 credits. The Free plan will let you geocode 6000 addresses daily. Click to learn more about pricing plans.
Watch this Tutorial on Youtube
Geocoding a list of addresses can be a bit intimidating at first. However, it’s easier than you might think! To prove to you that we’re not asking too much of you, we even created a short video.
Take 5 minutes to watch this quick video and learn how to get your address list geocoded and visualized in Excel or LibreOffice:
What's next
- Learn more about Geoapify Geocoding API >>
- Learn more about Batch Geocoding requests >>
- Try the API with Geocoding API Playground >>