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:
https://api.apilayer.net/positionstack/v1/forward?access_key=YOUR_ACCESS_KEY&query=1600%20Pennsylvania%20Ave%20NW,%20Washington%20DC&fields=results.label,results.map_urlExample 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": "https://positionstack.com/download/map.html?bbox=-77.036047,38.898175,-77.037047,38.897175&marker=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:
https://api.apilayer.net/positionstack/v1/forward?access_key=YOUR_ACCESS_KEY&query=1600%20Pennsylvania%20Ave%20NW,%20Washington%20DC&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": "https://positionstack.com/download/map.html?bbox=-77.036047,38.898175,-77.037047,38.897175&marker=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.