{"openapi":"3.0.0","info":{"title":"Positionstack","description":"The positionstack API was built to deliver forward and reverse geocoding data (converting addresses to geographic coordinates and vice versa) worldwide, in a lightweight JSON or GeoJSON format. Requests are made using a straightforward HTTP GET/POST URL structure and can be enriched with optional data modules.","version":"1.0.0"},"servers":[{"url":"https://api.positionstack.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"API Endpoints","description":"API Endpoints"}],"externalDocs":{"description":"Official Positionstack documentation (reference)","url":"https://positionstack.com/documentation"},"paths":{"/v1/forward":{"get":{"tags":["API Endpoints"],"summary":"Forward Geocoding.","description":"Converts a location (address, place name or POI) into geographic coordinates. Pass the location using the query parameter and optionally enrich the result with data modules.","operationId":"forwardGeocode","parameters":[{"$ref":"#/components/parameters/AccessKey"},{"name":"query","in":"query","description":"The location, address or place name to geocode. Example: 1600 Pennsylvania Ave NW, Washington","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Country"},{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Output"},{"$ref":"#/components/parameters/Fields"},{"$ref":"#/components/parameters/Callback"},{"$ref":"#/components/parameters/CountryModule"},{"$ref":"#/components/parameters/SunModule"},{"$ref":"#/components/parameters/TimezoneModule"},{"$ref":"#/components/parameters/BboxModule"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — one or more query parameters are invalid."},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}},"post":{"tags":["API Endpoints"],"summary":"Forward Geocoding (Batch).","description":"Geocodes multiple locations in a single request. Send a JSON array of query objects in the request body. Batch requests are only available on paid subscription plans.","operationId":"forwardBatch","parameters":[{"$ref":"#/components/parameters/AccessKey"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Output"},{"$ref":"#/components/parameters/Fields"},{"$ref":"#/components/parameters/CountryModule"},{"$ref":"#/components/parameters/SunModule"},{"$ref":"#/components/parameters/TimezoneModule"},{"$ref":"#/components/parameters/BboxModule"}],"requestBody":{"description":"A JSON object with a batch array of location query objects to geocode.","required":true,"content":{"application/json":{"schema":{"properties":{"batch":{"type":"array","items":{"properties":{"query":{"type":"string","example":"1600 Pennsylvania Ave NW, Washington"},"limit":{"type":"integer","example":1},"region":{"type":"string","example":"Washington"},"country":{"type":"string","example":"US"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodingResponse"}}}},"400":{"description":"Bad request — the JSON body is malformed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — one or more query parameters are invalid."},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}}},"/v1/reverse":{"get":{"tags":["API Endpoints"],"summary":"Reverse Geocoding.","description":"Converts geographic coordinates (or an IP address) into a human-readable address. Pass the coordinates as a comma-separated 'latitude,longitude' pair using the query parameter.","operationId":"reverseGeocode","parameters":[{"$ref":"#/components/parameters/AccessKey"},{"name":"query","in":"query","description":"The coordinates to reverse geocode, as 'latitude,longitude'. Example: 40.7638435,-73.9729691","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Output"},{"$ref":"#/components/parameters/Fields"},{"$ref":"#/components/parameters/Callback"},{"$ref":"#/components/parameters/CountryModule"},{"$ref":"#/components/parameters/SunModule"},{"$ref":"#/components/parameters/TimezoneModule"},{"$ref":"#/components/parameters/BboxModule"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — one or more query parameters are invalid."},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}},"post":{"tags":["API Endpoints"],"summary":"Reverse Geocoding (Batch).","description":"Reverse geocodes multiple coordinate pairs in a single request. Send a JSON array of query objects in the request body. Batch requests are only available on paid subscription plans.","operationId":"reverseBatch","parameters":[{"$ref":"#/components/parameters/AccessKey"},{"$ref":"#/components/parameters/Language"},{"$ref":"#/components/parameters/Output"},{"$ref":"#/components/parameters/Fields"},{"$ref":"#/components/parameters/CountryModule"},{"$ref":"#/components/parameters/SunModule"},{"$ref":"#/components/parameters/TimezoneModule"},{"$ref":"#/components/parameters/BboxModule"}],"requestBody":{"description":"A JSON object with a batch array of coordinate query objects to reverse geocode.","required":true,"content":{"application/json":{"schema":{"properties":{"batch":{"type":"array","items":{"properties":{"query":{"type":"string","example":"40.7638435,-73.9729691"},"limit":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodingResponse"}}}},"400":{"description":"Bad request — the JSON body is malformed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — one or more query parameters are invalid."},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}}}},"components":{"schemas":{"ApiError":{"type":"object","description":"Standard apilayer error envelope, shared by every error response.","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","required":["code","type"],"properties":{"code":{"type":"integer","description":"apilayer numeric error code (the code the API returns in the body, e.g. 101 for an invalid access key — NOT the HTTP status).","example":101},"type":{"type":"string","description":"Machine-readable error type.","example":"invalid_access_key"},"info":{"type":"string","description":"Human-readable error detail.","example":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}}}},"GeocodingResponse":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResultObject"}}},"type":"object","example":{"data":[{"latitude":38.897675,"longitude":-77.036547,"label":"1600 Pennsylvania Avenue NW, Washington, DC, USA","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","administrative_area":null,"neighbourhood":"White House Grounds","country":"United States","country_code":"US","map_url":"http://map.positionstack.com/38.897675,-77.036547"}]}},"ResultObject":{"properties":{"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"label":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"number":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"confidence":{"type":"number","format":"double"},"region":{"type":"string","nullable":true},"region_code":{"type":"string","nullable":true},"county":{"type":"string","nullable":true},"locality":{"type":"string","nullable":true},"administrative_area":{"type":"string","nullable":true},"neighbourhood":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true},"map_url":{"type":"string","nullable":true},"distance":{"description":"Distance in kilometres from the input coordinates (reverse geocoding only).","type":"number","format":"double","nullable":true},"country_module":{"$ref":"#/components/schemas/CountryModule"},"sun_module":{"$ref":"#/components/schemas/SunModule"},"timezone_module":{"$ref":"#/components/schemas/TimezoneModule"},"bbox_module":{"$ref":"#/components/schemas/BBoxModule"}},"type":"object"},"CountryModule":{"description":"Detailed country enrichment data (present when 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"},"area":{"type":"number"},"landlocked":{"type":"boolean"},"independent":{"type":"boolean"},"global":{"type":"object"},"dial":{"type":"array","items":{"type":"string"}},"currencies":{"type":"array","items":{"type":"object"},"nullable":true},"languages":{"type":"array","items":{"type":"object"},"nullable":true}},"type":"object","nullable":true},"BBoxModule":{"description":"Bounding box object returned when bbox_module=1.","properties":{"min_longitude":{"type":"number","format":"double"},"min_latitude":{"type":"number","format":"double"},"max_longitude":{"type":"number","format":"double"},"max_latitude":{"type":"number","format":"double"}},"type":"object"},"TimezoneModule":{"description":"Timezone metadata returned when timezone_module=1.","properties":{"id":{"description":"IANA timezone identifier (e.g. America/New_York).","type":"string"},"current_time":{"type":"string","format":"date-time"},"gmt_offset":{"description":"Offset from UTC in seconds.","type":"integer"},"code":{"description":"Abbreviated timezone code (e.g. EDT).","type":"string"},"is_daylight_saving":{"type":"boolean"}},"type":"object"},"SunModule":{"description":"Solar data returned when sun_module=1.","properties":{"sunrise":{"type":"string","format":"date-time"},"sunset":{"type":"string","format":"date-time"},"solar_noon":{"type":"string","format":"date-time"},"day_length":{"description":"Day length in seconds.","type":"integer"}},"type":"object"}},"parameters":{"AccessKey":{"name":"access_key","in":"query","description":"Your API access key, which can be found in your account dashboard.","required":true,"schema":{"type":"string"}},"Country":{"name":"country","in":"query","description":"Filter results by one or more comma-separated countries (ISO 3166-1 alpha-2 codes). Example: US,CA","required":false,"schema":{"type":"string"}},"Region":{"name":"region","in":"query","description":"Filter results by a specific administrative region.","required":false,"schema":{"type":"string"}},"Language":{"name":"language","in":"query","description":"Set the language of the results using a 2-letter language code. Example: en","required":false,"schema":{"type":"string"}},"Output":{"name":"output","in":"query","description":"Response output format. Available values: json (default), geojson, xml","required":false,"schema":{"type":"string","default":"json","enum":["json","geojson","xml"]}},"Fields":{"name":"fields","in":"query","description":"Comma-separated list of response fields/modules to include in the result.","required":false,"schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","description":"Limit the number of results returned. Default value is 10.","required":false,"schema":{"type":"integer","default":10}},"CountryModule":{"name":"country_module","in":"query","description":"Set to 1 to enrich results with detailed country data.","required":false,"schema":{"type":"integer","enum":[0,1]}},"SunModule":{"name":"sun_module","in":"query","description":"Set to 1 to enrich results with sunrise/sunset data.","required":false,"schema":{"type":"integer","enum":[0,1]}},"TimezoneModule":{"name":"timezone_module","in":"query","description":"Set to 1 to enrich results with timezone data.","required":false,"schema":{"type":"integer","enum":[0,1]}},"BboxModule":{"name":"bbox_module","in":"query","description":"Set to 1 to enrich results with bounding box data.","required":false,"schema":{"type":"integer","enum":[0,1]}},"Callback":{"name":"callback","in":"query","description":"JSONP callback function name. If present, the JSON response will be wrapped in this function.","required":false,"schema":{"type":"string"}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"access_key","in":"query"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"account_on_hold":{"summary":"account_on_hold","value":{"success":false,"error":{"code":107,"type":"account_on_hold","info":"Your account currently has open invoices and API has been automatically disabled. Please settle your open balance or downgrade to the Free Plan to restore API access. [Support: support@apilayer.com]"}}},"invalid_access_key":{"summary":"invalid_access_key","value":{"success":false,"error":{"code":101,"type":"invalid_access_key","info":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}},"missing_access_key":{"summary":"missing_access_key","value":{"success":false,"error":{"code":101,"type":"missing_access_key","info":"You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]"}}},"inactive_user":{"summary":"inactive_user","value":{"success":false,"error":{"code":102,"type":"inactive_user","info":"Permission denied - User not active."}}}}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"https_access_restricted":{"summary":"https_access_restricted","value":{"success":false,"error":{"code":105,"type":"https_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support HTTPS Encryption."}}},"function_access_restricted":{"summary":"function_access_restricted","value":{"success":false,"error":{"code":105,"type":"function_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support this API Function."}}},"api_access_blocked":{"summary":"api_access_blocked","value":{"success":false,"error":{"code":104,"type":"api_access_blocked","info":"Your API access has been temporarily disabled. Please upgrade your Subscription Plan or contact support."}}}}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"invalid_api_function":{"summary":"invalid_api_function","value":{"success":false,"error":{"code":103,"type":"invalid_api_function","info":"This API Function does not exist."}}},"404_not_found":{"summary":"404_not_found","value":{"success":false,"error":{"code":404,"type":"404_not_found","info":"404 - The requested resource could not be found. Please try again or contact support."}}}}}}},"RateLimitReached":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"usage_limit_reached":{"summary":"usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"usage_limit_reached","info":"Your monthly usage limit has been reached. Please upgrade your Subscription Plan."}}},"daily_usage_limit_reached":{"summary":"daily_usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"daily_usage_limit_reached","info":"Your daily usage limit has been reached. Please try again tomorrow or upgrade your subscription plan."}}},"fair_use_limit_reached":{"summary":"fair_use_limit_reached","value":{"success":false,"error":{"code":104,"type":"fair_use_limit_reached","info":"Your fair use limit has been reached. [Please contact support: support@apilayer.com]"}}},"rate_limit_reached":{"summary":"rate_limit_reached","value":{"success":false,"error":{"code":106,"type":"rate_limit_reached","info":"You have exceeded the maximum rate limitation allowed on your subscription plan. Please refer to the \"Rate Limits\" section of the API Documentation for details. "}}}}}}},"InternalError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"internal_error":{"summary":"internal_error","value":{"success":false,"error":{"code":0,"type":"internal_error","info":"An error has occured. [Technical Support: support@apilayer.com]"}}}}}}},"Maintenance":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"maintenance_mode":{"summary":"maintenance_mode","value":{"success":false,"error":{"code":503,"type":"maintenance_mode","info":""}}}}}}}}}}