How To Get Started With Powerful A Geo API Service Using NodeJS

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.

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).

 

How can I Access positionstack API?

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

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:

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.

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.

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):

 

 

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):

 

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):

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:

 

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!

 

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