openapi: 3.0.3
info:
title: positionstack
description: |
Forward and Reverse Batch Geocoding REST API by positionstack (apilayer).
Convert addresses to coordinates (forward geocoding) and coordinates to addresses
(reverse geocoding). Supports batch requests, multiple output formats
(JSON, XML, GeoJSON), 2+ billion global places, and add-on modules for timezone,
bounding box, country, and sun (sunrise/sunset) data.
version: "1.0.0"
contact:
name: positionstack Support
email: [email protected]
url: https://positionstack.com/
license:
name: Commercial
url: https://www.ideracorp.com/legal/APILayer
termsOfService: https://www.ideracorp.com/legal/APILayer
servers:
- url: https://api.positionstack.com/v1
description: Production API (HTTPS available on Basic plan and above)
- url: http://api.positionstack.com/v1
description: Production API (HTTP - Free plan)
security:
- AccessKeyAuth: []
tags:
- name: Forward Geocoding
description: Convert addresses, place names, or partial location strings into geographic coordinates.
- name: Reverse Geocoding
description: Convert latitude/longitude coordinates into a full address with locality, region, and country.
- name: Batch Geocoding
description: Run multiple forward or reverse geocoding lookups in a single request (Professional plan and above).
paths:
/forward:
get:
operationId: forwardGeocode
summary: Forward Geocode an Address
description: |
Convert one or more location strings (street, city, place name, postal code)
into geographic coordinates and structured address data. Supply one or more
comma-separated queries to perform a batch request (Professional plan and above).
tags:
- Forward Geocoding
- Batch Geocoding
parameters:
- $ref: '#/components/parameters/AccessKey'
- name: query
in: query
required: true
description: |
The address, place name, or location string to geocode. To run a batch
request, pass multiple comma-separated queries (Professional plan and above).
schema:
type: string
example: "1600 Pennsylvania Ave NW, Washington DC"
- $ref: '#/components/parameters/Country'
- $ref: '#/components/parameters/Region'
- $ref: '#/components/parameters/Bbox'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Language'
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Output'
- $ref: '#/components/parameters/Callback'
- $ref: '#/components/parameters/CountryModule'
- $ref: '#/components/parameters/SunModule'
- $ref: '#/components/parameters/TimezoneModule'
- $ref: '#/components/parameters/BboxModule'
responses:
'200':
description: Successful geocoding response.
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodingResponse'
application/xml:
schema:
$ref: '#/components/schemas/GeocodingResponse'
application/geo+json:
schema:
$ref: '#/components/schemas/GeoJSONFeatureCollection'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
/reverse:
get:
operationId: reverseGeocode
summary: Reverse Geocode Coordinates
description: |
Convert one or more latitude/longitude coordinate pairs into structured
address data. Supply one or more semicolon-separated coordinate pairs
(or comma-separated batched queries) to perform a batch request
(Professional plan and above).
tags:
- Reverse Geocoding
- Batch Geocoding
parameters:
- $ref: '#/components/parameters/AccessKey'
- name: query
in: query
required: true
description: |
Latitude and longitude coordinate pair as a comma-separated string
("LAT,LON"). For batch reverse lookups, separate multiple pairs with
a semicolon (Professional plan and above).
schema:
type: string
pattern: '^-?\d+(\.\d+)?,-?\d+(\.\d+)?(;-?\d+(\.\d+)?,-?\d+(\.\d+)?)*$'
example: "40.7638435,-73.9729691"
- $ref: '#/components/parameters/Country'
- $ref: '#/components/parameters/Region'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Language'
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Output'
- $ref: '#/components/parameters/Callback'
- $ref: '#/components/parameters/CountryModule'
- $ref: '#/components/parameters/SunModule'
- $ref: '#/components/parameters/TimezoneModule'
- $ref: '#/components/parameters/BboxModule'
responses:
'200':
description: Successful reverse geocoding response.
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodingResponse'
application/xml:
schema:
$ref: '#/components/schemas/GeocodingResponse'
application/geo+json:
schema:
$ref: '#/components/schemas/GeoJSONFeatureCollection'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
securitySchemes:
AccessKeyAuth:
type: apiKey
in: query
name: access_key
description: API access key obtained from your positionstack dashboard.
parameters:
AccessKey:
name: access_key
in: query
required: true
description: Your positionstack API access key.
schema:
type: string
Country:
name: country
in: query
required: false
description: |
Filter results to one or more ISO 3166 alpha-2 country codes (comma separated).
schema:
type: string
example: "US,CA"
Region:
name: region
in: query
required: false
description: Filter results by region or state name.
schema:
type: string
example: "California"
Bbox:
name: bbox
in: query
required: false
description: |
Bounding box filter as `min_lon,min_lat,max_lon,max_lat` to restrict the
geographic area of the search.
schema:
type: string
example: "-74.2591,40.4774,-73.7004,40.9176"
Limit:
name: limit
in: query
required: false
description: Maximum number of results returned. Defaults to 10, maximum 80.
schema:
type: integer
default: 10
minimum: 1
maximum: 80
Language:
name: language
in: query
required: false
description: Two-letter ISO 639-1 language code for localized results.
schema:
type: string
example: "en"
Fields:
name: fields
in: query
required: false
description: |
Comma-separated whitelist of fields to include in the response (e.g. `results.latitude,results.longitude`).
Defaults to all fields.
schema:
type: string
default: "all"
Output:
name: output
in: query
required: false
description: Response output format.
schema:
type: string
enum: [json, xml, geojson]
default: json
Callback:
name: callback
in: query
required: false
description: JSONP callback function name (JSON output only).
schema:
type: string
CountryModule:
name: country_module
in: query
required: false
description: |
Set to `1` to enrich results with country-level data such as ISO codes,
capital, population, currency, language, flag URLs, and dial code.
schema:
type: integer
enum: [0, 1]
default: 0
SunModule:
name: sun_module
in: query
required: false
description: |
Set to `1` to enrich results with sunrise, sunset, and solar transit times
for the location.
schema:
type: integer
enum: [0, 1]
default: 0
TimezoneModule:
name: timezone_module
in: query
required: false
description: |
Set to `1` to enrich results with timezone name, abbreviation, GMT offset,
and DST status.
schema:
type: integer
enum: [0, 1]
default: 0
BboxModule:
name: bbox_module
in: query
required: false
description: |
Set to `1` to include the bounding box coordinates of each returned result.
schema:
type: integer
enum: [0, 1]
default: 0
responses:
Unauthorized:
description: Missing or invalid access_key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Subscription does not permit this request (e.g. HTTPS or batch on Free plan).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Monthly request quota exhausted or rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalError:
description: An unexpected server-side error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
GeocodingResponse:
type: object
description: A wrapper containing the array of geocoded location results.
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location'
Location:
type: object
description: A single geocoded location result.
properties:
latitude:
type: number
format: double
description: Geographic latitude in decimal degrees.
longitude:
type: number
format: double
description: Geographic longitude in decimal degrees.
type:
type: string
description: |
Result classification (e.g. `address`, `venue`, `street`, `neighbourhood`,
`borough`, `locality`, `county`, `macrocounty`, `region`, `macroregion`,
`country`, `coarse`, `postalcode`).
name:
type: string
description: The short name of the location (e.g. building or street name).
number:
type: string
nullable: true
description: Building or street number.
postal_code:
type: string
nullable: true
description: Postal/ZIP code of the address.
street:
type: string
nullable: true
description: Street name.
confidence:
type: number
format: float
minimum: 0
maximum: 1
description: Confidence score (0.0-1.0) representing match quality.
region:
type: string
nullable: true
description: Name of the region (state, province).
region_code:
type: string
nullable: true
description: ISO 3166-2 region code.
county:
type: string
nullable: true
description: County name.
locality:
type: string
nullable: true
description: Locality / city name.
administrative_area:
type: string
nullable: true
description: Administrative area name.
neighbourhood:
type: string
nullable: true
description: Neighbourhood name.
country:
type: string
description: Country name.
country_code:
type: string
description: ISO 3166 alpha-3 country code.
continent:
type: string
nullable: true
description: Continent name.
label:
type: string
description: Fully formatted label for the result.
map_url:
type: string
format: uri
nullable: true
description: Embeddable map URL for the location (iFrame).
distance:
type: number
format: float
nullable: true
description: Distance (meters) from the query coordinates (reverse geocoding only).
bbox_module:
type: array
nullable: true
description: Bounding box of the result as `[min_lon, min_lat, max_lon, max_lat]` (requires `bbox_module=1`).
items:
type: number
format: double
country_module:
$ref: '#/components/schemas/CountryModuleData'
timezone_module:
$ref: '#/components/schemas/TimezoneModuleData'
sun_module:
$ref: '#/components/schemas/SunModuleData'
CountryModuleData:
type: object
nullable: true
description: Country-level enrichment data (requires `country_module=1`).
properties:
latitude:
type: number
format: double
longitude:
type: number
format: double
common_name:
type: string
official_name:
type: string
capital:
type: string
flag:
type: string
format: uri
area:
type: number
format: float
description: Area in square kilometers.
landlocked:
type: boolean
independent:
type: boolean
global:
type: object
properties:
alpha2:
type: string
alpha3:
type: string
numeric_code:
type: string
region:
type: string
subregion:
type: string
region_code:
type: string
subregion_code:
type: string
world_region:
type: string
continent_name:
type: string
continent_code:
type: string
dial:
type: object
properties:
calling_code:
type: string
national_prefix:
type: string
international_prefix:
type: string
currencies:
type: array
items:
type: object
properties:
symbol:
type: string
code:
type: string
name:
type: string
numeric:
type: string
minor_unit:
type: string
languages:
type: object
additionalProperties:
type: string
TimezoneModuleData:
type: object
nullable: true
description: Timezone enrichment data (requires `timezone_module=1`).
properties:
name:
type: string
description: IANA timezone name (e.g. `America/New_York`).
abbreviation:
type: string
offset_sec:
type: integer
offset_string:
type: string
gmt_offset:
type: integer
is_dst:
type: boolean
SunModuleData:
type: object
nullable: true
description: Sunrise/sunset data (requires `sun_module=1`).
properties:
rise:
type: object
properties:
time:
type: integer
description: Unix timestamp of sunrise.
astronomical:
type: integer
civil:
type: integer
nautical:
type: integer
set:
type: object
properties:
time:
type: integer
description: Unix timestamp of sunset.
astronomical:
type: integer
civil:
type: integer
nautical:
type: integer
transit:
type: integer
description: Unix timestamp of solar transit (noon).
GeoJSONFeatureCollection:
type: object
description: Standard GeoJSON FeatureCollection envelope (when `output=geojson`).
properties:
type:
type: string
enum: [FeatureCollection]
features:
type: array
items:
$ref: '#/components/schemas/GeoJSONFeature'
GeoJSONFeature:
type: object
properties:
type:
type: string
enum: [Feature]
geometry:
type: object
properties:
type:
type: string
enum: [Point]
coordinates:
type: array
minItems: 2
maxItems: 2
items:
type: number
format: double
properties:
$ref: '#/components/schemas/Location'
ErrorResponse:
type: object
description: Standard apilayer/positionstack error envelope.
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
description: |
Numeric error code (e.g. 101 invalid_access_key, 103 invalid_api_function,
104 usage_limit_reached, 105 function_access_restricted, 601 invalid_query,
602 no_results_found, 603 invalid_latitude, 604 invalid_longitude, 605 invalid_bbox).
type:
type: string
description: Error type slug.
info:
type: string
description: Human-readable error description.