Unparalleled suite of productivity-boosting Web APIs & cloud-based micro-service applications for developers and companies of any size.

APIAutomationJavascriptLocation

Geocoding | Getting Started With a Geo API Service Using NodeJS

Geocode with Node JS

Ever wonder how apps like Uber know exactly where you are? They use a process called geocoding, which converts addresses into map coordinates. Positionstack is an API that makes geocoding easy.

This blog will explain positionstack and why it’s helpful. It covers over 2 billion places worldwide. We’ll also discuss its features, like batch geocoding and support for many languages, which make it popular with developers.

You’ll learn how to use the positionstack API, with simple examples for finding locations and addresses. We’ll show you how to do this using Node.js, a programming language.

By the end of this blog, you’ll see why positionstack is a great tool for anyone who wants to add location features to their apps.

Developers geocoding

What is positionstack, and What Makes it Powerful?

positionstack is an API service that delivers a straightforward and reliable solution for forward and reverse geocoding. positionstack covers more than 2 billion places and addresses worldwide. 

Among its features, the positionstack API includes batch geocoding, multi-language support, embeddable map URLs, and more. positionstack can deliver geolocation API results in JSON, XML, or geocode-specific GeoJSON. The API’s average response times range between 10ms and 100ms depending on the size of your request.

  • Forward Geocoding
  • Reverse Geocoding
  • Batch Requests
  • Embeddable Maps
  • JSON, XML & GeoJSON
  • Multiple Languages

positionstack has become the go to geolocation API for many businesses. Here is why positionstack users request 1+ billion geocode API lookups each day:

  • 2+ Billion Addresses Covered Around the World!
  • Real-Time Geocoding: Geocode any global address or set of coordinates in real-time and lookup location components, country and timezone data, and plenty more.
  • Scalable Infrastructure: scalable apilayer cloud infrastructure The scalable apilayer cloud infrastructure powers positionstack allowing it to handle billions of geocoding requests with response times between 10 and 100 ms.
  • Worldwide Coverage: Take advantage of an extensive set of worldwide geocoding data, sourced from high-quality data vendors and updated multiple times per day.
  • Fair Pricing: You get 10,000 monthly geocode requests for free. In case you ever need more, premium geocoding subscriptions start at just $9.99 per month.

apilayer, an Austrian technology company that builds a variety of reliable programming interfaces (APIs) builds and maintains the positionstack API. apilayer make cutting-edge APIs affordable for developers and startups. Browse all available apilayer products here.

Simply put, positionstack is the most advanced, lightweight, affordable, and easy-to-use geocoding solution on the market. This article outlines in detail its diverse API endpoints, available options, and tutorials with Node.js and other platforms (Postman and RAD Studio REST Debugger).

JSON response

 

How can I Access positionstack API?

First, get your API Credentials here, and set up your subscription plan:

Positionstack

You can monitor your usage via this dashboard

API Access Key & Authentication

Next, to check if everything is working properly, just simply run this URL in your favorite web browser:

You should see this API response in your browser:

position Stack JSON response

API Errors

If your API request fails, the API returns an error object. This contains the sub-objects code and message that indicates the type of error that has occurred.

Here are the most common API errors:

Code Type Description
401 invalid_access_key An invalid API access key was supplied.
401 missing_access_key No API access key was supplied.
401 inactive_user The given user account is inactive.
403 https_access_restricted HTTPS access is not supported on the current subscription plan.
403 function_access_restricted The given API endpoint is not supported on the current subscription plan.
404 invalid_api_function The given API endpoint does not exist.
404 404_not_found Resource not found.
429 usage_limit_reached The given user account has reached its monthly allowed request volume.
429 rate_limit_reached The given user account has reached the rate limit.
500 internal_error An internal error occurred.

 

What Forward Geocoding Endpoints are Available via the API?

Forward Geocoding is the process of converting a free-text address or place to location data. To make a forward geocoding request, use the API’s forward endpoint and specify your query using the query parameter.

Here are the HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your account dashboard.
query [Required] Specify your query as a free-text address, place name, or using any other common text-based location identifier (e.g. postal code, city name, region name).
country [Optional] Filter geocoding results by one or multiple comma-separated 2-letter (e.g. AU) or 3-letter country codes (e.g. AUS). Example: country=AU, CA to filter by Australia and Canada.Download: Supported Countries (CSV)
region [Optional] Filter geocoding results by specifying a region. This could be a neighborhood, district, city, county, state, or administrative area. Example: region=Berlin to filter by locations in Berlin.
language [Optional] Translate specific API response objects by specifying the 2-letter (e.g. en) or the 3-letter code (e.g. eng) of your preferred language. (Default: English)
country_module [Optional] Set to 1 to enable the Country Module to include more extensive country data in your API response. Read more about this in the Country Module section.
sun_module [Optional] Set to 1 to enable the Sun Module to include astrology data in your API response. Read more about this in the Sun Module section.
timezone_module [Optional] Set to 1 to enable the Timezone Module to include timezone data in your API response. Read more about this in the Timezone Module section.
bbox_module [Optional] Set to 1 to enable the Bounding Box Module to include boundary coordinates in your API response. Read more about this in the Bounding Box Module section.
limit [Optional] Specify a limit between 1 and 80 to limit the number of results returned per geocoding query. Batch requests can contain multiple geocoding queries. (Default: 10 results)
fields [Optional] Specify one or multiple response field(s) to decrease API response size. Learn how to use this option in the Specify Response Fields section.
output [Optional] Specify your preferred API output format. Available values: JSON (default), XML and GeoJSON.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.

Each API response consists of 18 different response objects:

Response Object Description
data Returns two large arrays of data: request and results, explained in more detail below.
results Returns an array of location results for this API request. The number of sub-arrays directly depends on the value specified limit value. All sub-arrays and sub-objects are listed below.
results > latitude Returns the latitude coordinate associated with the location result.
results > longitude Returns the longitude coordinate associated with the location result.
results > label Returns the formatted place name or address.
results > name Returns the name of the location result. This could be a place name, address, postal code, and more.
results > type Returns the type of location result. Here is the list of all available Location Types: venue, address, street, neighborhood, borough, localadmin, locality, county, macrocountry, region, macroregion, country, coarse, postalcode.
results > number Returns the street or house number associated with the location result.
results > street Returns the street name associated with the location result.
results > postal_code Returns the postal or ZIP code associated with the location result.
results > confidence Returns a confidence score between 0 (0% confidence) and 1 (100% confidence) associated with the location result.
results > region Returns the name of the region associated with the location result.
results > region_code Returns the region code associated with the location result.
results > administrative_area Returns the name of the administrative area associated with the location result.
results > neighborhood Returns the name of the neighborhood associated with the location result.
results > country Returns the common name of the country associated with the location result.
results > country_code Returns the ISO 3166 Alpha 2 (two letters) code of the country associated with the location result.
results > map_url Returns an embeddable map associated with the location result.

 

What Reverse Geocoding Endpoints are Available via the API?

Reverse Geocoding is the process of converting coordinates (latitude & longitude) or an IP address to location data. To make a reverse geocoding request, use the API’s reverse endpoint and specify your query using the query parameter.

HTTP GET Request Parameters

Here are the HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your account dashboard.
query [Required] Specify your query as coordinates in the format latitude,longitude (e.g. query=40.7638435,-73.9729691) or use an IP address for automated coordinate-detection (e.g. query=72.229.28.185).
country [Optional] Filter geocoding results by one or multiple comma-separated 2-letter (e.g. AU) or 3-letter country codes (e.g. AUS). Example: country=AU, CA to filter by Australia and Canada.Download: Supported Countries (CSV)
region [Optional] Filter geocoding results by specifying a region. This could be a neighborhood, district, city, county, state, or administrative area. Example: region=Berlin to filter by locations in Berlin.
language [Optional] Translate specific API response objects by specifying the 2-letter (e.g. en) or the 3-letter code (e.g. eng) of your preferred language. (Default: English)
country_module [Optional] Set to 1 to enable the Country Module to include more extensive country data in your API response. Read more about this in the Country Module section.
sun_module [Optional] Set to 1 to enable the Sun Module to include astrology data in your API response. Read more about this in the Sun Module section.
timezone_module [Optional] Set to 1 to enable the Timezone Module to include timezone data in your API response. Read more about this in the Timezone Module section.
bbox_module [Optional] Set to 1 to enable the Bounding Box Module to include boundary coordinates in your API response. Read more about this in the Bounding Box Module section.
limit [Optional] Specify a limit between 1 and 80 to limit the number of results returned per geocoding query. Batch requests can contain multiple geocoding queries. (Default: 10 results)
fields [Optional] Specify one or multiple response field(s) to decrease API response size. Learn how to use this option in the Specify Response Fields section.
output [Optional] Specify your preferred API output format. Available values: JSON (default), XML and GeoJSON.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.

Response Objects

Each API response consists of 20 different response objects:

Response Object Description
data Returns two large arrays of data: request and results, explained in more detail below.
results Returns an array of location results for this API request. The number of sub-arrays directly depends on the value specified limit value. All sub-arrays and sub-objects are listed below.
results > latitude Returns the latitude coordinate associated with the location result.
results > longitude Returns the longitude coordinate associated with the location result.
results > label Returns the formatted place name or address.
results > name Returns the name of the location result. This could be a place name, address, postal code, and more.
results > type Returns the type of location result. Here is the list of all available Location Types: venue, address, street, neighborhood, borough, localadmin, locality, county, macrocountry, region, macroregion, country, coarse, postalcode.
results > distance Returns the distance (in meters) between the location result and the coordinates specified in the query parameter. Only applicable for reverse geocoding.
results > number Returns the street or house number associated with the location result.
results > street Returns the street name associated with the location result.
results > postal_code Returns the postal or ZIP code associated with the location result.
results > confidence Returns a confidence score between 0 (0% confidence) and 1 (100% confidence) associated with the location result.
results > region Returns the name of the region associated with the location result.
results > region_code Returns the region code associated with the location result.
results > administrative_area Returns the name of the administrative area associated with the location result.
results > neighborhood Returns the name of the neighborhood associated with the location result.
results > country Returns the common name of the country associated with the location result.
results > country_code Returns the ISO 3166 Alpha 2 (two letters) code of the country associated with the location result.
results > map_url Returns an embeddable map associated with the location result.

 

How can I Perform Forward Geocoding with Node.js?

The positionstack API is compatible with all major programming languages out there.

Use the following code to make a Forward Geocoding API request using Node.js:

Here is the API response inside your Node.js IDE (here, I’m using Atom for this example):

Atom runner response

 

 

How can I Perform Reverse Geocoding with Node.js?

Use the following code to make a Reverse Geocoding API request using Node.js, don’t forget that you need the latitude and longitude as input for the query search:

Here is the API response inside your Node.js IDE (here, I’m using Atom for this example):

Atom response for geocoding api

 

Bonus: API Request using other Platforms

How can I Make an API Request using RAD Studio REST Debugger?

First, download Delphi REST Debugger here.

Choose the GET method, and send the request to the following URL (example of Reverse Geocoding):

Geocoding api testing

After getting the API responses you need, and you want to create Desktop apps based on it using Delphi, please refer to this article to get started:

https://blogs.embarcadero.com/using-apilayer-rest-apis-from-delphi/

How can I Make an API Request using Postman?

If this is your first time using Postman, you can read about the installation guide in our blogpost here:

https://blog.apilayer.com/easily-spider-websites-using-node-js-and-powerful-rest-apis/

Choose the GET method, and send the request to the following URL:

Postman response for a geocoding api

 

Are you Ready to Integrate Powerful Geocoding Features into Your Apps?

As you can see, there are many accurate forward & reverse batch geocoding REST API endpoints provided by the positionstack REST API. You can connect these to any platform and any programming language you work with.

In this article, we show you a basic demo of how you can use the positionstack REST API to perform Forward and Reverse Geocoding.

Take advantage of the free tier on positionstack! We strongly recommend you to upgrade your subscription plan if you need more powerful features (HTTPS Encryption, Extended Rate Limit, JSON; XML & GeoJSON, Embeddable Maps, and many more). If that is not enough, contact us for a custom solution. We can’t wait to see what you build with our REST API!

FAQs

1. What is geocoding?

Geocoding turns addresses into map points. For example, it changes “1600 Amphitheatre Parkway, Mountain View, CA” into coordinates (like latitude 37.423021 and longitude -122.083739) that show where it is on a map.

2. How does geocoding work?

Geocoding uses a special service (like Google Maps) to find the exact spot on a map for an address. It looks at databases, algorithms, and map data to do this.

3. What is reverse geocoding?

Reverse geocoding is the opposite. It takes coordinates and turns them into an address that people can understand. For example, it changes latitude and longitude into “1600 Amphitheatre Parkway, Mountain View, CA.”

4. What do people use geocoding for?

Geocoding helps in mapping apps (like Google Maps), finding nearby places (like restaurants), and systems that use maps to analyze and display information.

5. Are there any problems with geocoding?

Sometimes geocoding can be wrong, especially in areas with few people. Also, old or wrong address info can cause issues. There are also privacy concerns because geocoding often involves sharing location data.

Head over and sign up for free to start integrating precise and rich forward & reverse geolocation data to your apps today!

Related posts
APIAviation Data

The Role of APIs in Modernizing the Aviation Industry

APICurrencyFinance

Currency Exchange Rate API: Key Trends for the Coming Years

API

Introducing APILayer's Platinum Support: Elevate Your API Experience

APIFinancestock data

What to Expect: Financial Data API Trends for the Next Few Years

Leave a Reply

Your email address will not be published. Required fields are marked *