Options
Specify Response Fields
Depending on whether or not batch requests are made and additional data modules are enabled, API response files can be large in size. To reduce bandwidth and limit your API result to return only the fields your application requires, you can specify one or multiple preferred response fields using the API's fields parameter.
Example:
fields = results // returns only the "results" object
fields = results.map_url // returns only the embeddable map URL inside "results"
fields = results.latitude,results.longitude // returns both coordinates inside "results"
fields = country.flag // returns only the flag icon inside "country"
Example API Request:
Sign Up to Run API Request
https://api.positionstack.com/v1/forward
? access_key = YOUR_ACCESS_KEY
& query = 1600 Pennsylvania Ave NW, Washington DC
& fields = results.label,results.map_url
Example API Response:
As you can see below, the API returns a lightweight API response only containing the two specified fields.
{
"label": "1600 Pennsylvania Avenue NW, Washington, DC, USA",
"map_url": "http://map.positionstack.com/38.897675,-77.036547"
}Specify Output Format
By default, all geocoding results are returned in standard JSON format. For customers subscribed to the Basic Plan or higher, there is an additional output parameter that can be used to switch their preferred output format to XML or GeoJSON.
Example API Request:
Sign Up to Run API Request
https://api.positionstack.com/v1/forward
? access_key = YOUR_ACCESS_KEY
& query = 1600 Pennsylvania Ave NW, Washington DC
& output = geojsonExample API Response:
{
"data": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-77.036547,
38.897675
]
},
"properties": {
"name": "1600 Pennsylvania Avenue NW",
"type": "address",
"number": "1600",
"street": "Pennsylvania Avenue NW",
"postal_code": "20500",
"confidence": 1,
"region": "District of Columbia",
"region_code": "DC",
"neighbourhood": "White House Grounds",
"country": {
"latitude": "39.44325637817383",
"longitude": "-98.95733642578125",
"common_name": "United States",
"official_name": "United States of America",
"capital": "Washington D.C.",
"flag": "??",
"area": 9372610,
"landlocked": false,
"independent": true,
"global": {
"alpha2": "US",
"alpha3": "USA",
"numeric_code": "840",
"region": "Americas",
"subregion": "Northern America",
"region_code": "019",
"subregion_code": "021",
"world_region": "AMER",
"continent_name": "North America",
"continent_code": "NA"
},
"dial": {
"calling_code": "1",
"national_prefix": "1",
"international_prefix": "011"
},
"currencies": [
{
"symbol": "$",
"code": "USD",
"name": "US Dollar",
"numeric": 840,
"minor_unit": 2
}
],
"languages": {
"eng": "English"
}
},
"map_url": "http://map.positionstack.com/38.897675,-77.036547",
"label": "1600 Pennsylvania Avenue NW, Washington, DC, USA"
},
"sun": {
"rise": {
"time": 1575461426,
"astronomical": 1575455738,
"civil": 1575459659,
"nautical": 1575457670
},
"set": {
"time": 1575495970,
"astronomical": 1575501659,
"civil": 1575497738,
"nautical": 1575499726
},
"transit": 1575478698
},
"timezone": {
"name": "America/New_York",
"offset_sec": -18000,
"offset_string": "-05:00"
}
}
]
}
}GeoJSON Specification: To learn more about GeoJSON and how it is used, please take a look at the following GeoJSON article.