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.
Table of Contents
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).
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:
|
1 |
http://api.positionstack.com/v1/forward?access_key=YOUR_ACCESS_KEY&query=1600%20Pennsylvania%20Ave%20NW,%20Washington%20DC |
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.
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
const axios = require('axios'); const params = { access_key: 'YOUR_ACCESS_KEY', query: '1600 Pennsylvania Ave NW, Washington DC' } axios.get('http://api.positionstack.com/v1/forward', {params}) .then(response => { console.log(response.data); }).catch(error => { console.log(error); }); |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
const axios = require('axios'); const params = { access_key: 'YOUR_ACCESS_KEY', query: '38.897675, -77.036547' } axios.get('http://api.positionstack.com/v1/reverse', {params}) .then(response => { console.log(response.data); }).catch(error => { console.log(error); }); |
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):
|
1 |
http://api.positionstack.com/v1/reverse?access_key=YOUR_ACCESS_KEY&query=40.7638435,-73.9729691 |
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:
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:
Choose the GET method, and send the request to the following URL:
|
1 |
http://api.positionstack.com/v1/reverse?access_key=YOUR_ACCESS_KEY&query=40.7638435,-73.9729691 |
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.
