openapi: 3.2.0
info:
title: Neutrino Geolocation API
version: 3.7.2
contact:
name: Neutrino API
url: https://www.neutrinoapi.com/
email: tech@neutrinoapi.com
description: 'Operations tagged Geolocation across 2 of this provider''s published API definitions: neutrino-api-openapi-3.1.json, neutrino-api-swagger-2.0.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://neutrinoapi.net
description: Multicloud endpoint utilizing both GCP and AWS with IP anycast load balancing, DNS based geoproximity and cloud failover
variables: {}
- url: https://aws.neutrinoapi.net
description: AWS only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://gcp.neutrinoapi.net
description: GCP only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://neutrinoapi.com
description: Backup endpoint utilizing a seperate top-level domain and IP addresses
variables: {}
- url: https://eu.neutrinoapi.net
description: European Union geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://aus.neutrinoapi.net
description: Australia geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://usa.neutrinoapi.net
description: United States geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
security:
- user-id: []
api-key: []
tags:
- name: Geolocation
description: APIs for geolocation tasks
paths:
/ip-info:
parameters: []
servers:
- url: https://neutrinoapi.net
description: Multicloud endpoint utilizing both GCP and AWS with IP anycast load balancing, DNS based geoproximity and cloud failover
variables: {}
- url: https://aws.neutrinoapi.net
description: AWS only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://gcp.neutrinoapi.net
description: GCP only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://neutrinoapi.com
description: Backup endpoint utilizing a seperate top-level domain and IP addresses
variables: {}
- url: https://eu.neutrinoapi.net
description: European Union geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://aus.neutrinoapi.net
description: Australia geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://usa.neutrinoapi.net
description: United States geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
get:
tags:
- Geolocation
summary: IP Info
description: Get location information about an IP address and do reverse DNS (PTR) lookups
operationId: IPInfo
parameters:
- name: ip
in: query
description: An IPv4 or IPv6 address. Accepts standard IP notation and also CIDR notation
required: true
style: form
explode: true
schema:
type: string
examples:
- 1.1.1.1
- name: reverse-lookup
in: query
description: Do a reverse DNS (PTR) lookup. This option can add extra delay to the request so only use it if you need it
style: form
explode: true
schema:
type: boolean
default: false
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/IPInfoResponse'
'400':
description: Your API request has been rejected. Check error code for details
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You have failed to authenticate
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: We messed up, sorry! Your request has caused a fatal exception
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
default:
description: We messed up, sorry! Your request has caused an error
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
deprecated: false
/geocode-reverse:
parameters: []
servers:
- url: https://neutrinoapi.net
description: Multicloud endpoint utilizing both GCP and AWS with IP anycast load balancing, DNS based geoproximity and cloud failover
variables: {}
- url: https://aws.neutrinoapi.net
description: AWS only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://gcp.neutrinoapi.net
description: GCP only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://neutrinoapi.com
description: Backup endpoint utilizing a seperate top-level domain and IP addresses
variables: {}
- url: https://eu.neutrinoapi.net
description: European Union geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://aus.neutrinoapi.net
description: Australia geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://usa.neutrinoapi.net
description: United States geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
get:
tags:
- Geolocation
summary: Geocode Reverse
description: Convert a geographic coordinate (latitude and longitude) into a real world address
operationId: GeocodeReverse
parameters:
- name: latitude
in: query
description: The location latitude in decimal degrees format
style: form
explode: true
schema:
type: string
examples:
- '-41.2775847'
- name: longitude
in: query
description: The location longitude in decimal degrees format
style: form
explode: true
schema:
type: string
examples:
- '174.7775229'
- name: language-code
in: query
description: 'The language to display results in, available languages are: <ul> <li>ar, de, en, es, fr, it, ja, nl, pt, ru, zh</li> </ul>'
style: form
explode: true
schema:
type: string
default: en
- name: zoom
in: query
description: 'The zoom level to respond with: <br> <ul> <li>address - the most precise address available</li> <li>street - the street level</li> <li>city - the city level</li> <li>state - the state level</li> <li>country - the country level</li> </ul>'
style: form
explode: true
schema:
type: string
default: address
- name: geohash
in: query
description: Reverse lookup by a geohash instead of using latitude and longitude
style: form
explode: true
schema:
type: string
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodeReverseResponse'
'400':
description: Your API request has been rejected. Check error code for details
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You have failed to authenticate
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: We messed up, sorry! Your request has caused a fatal exception
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
default:
description: We messed up, sorry! Your request has caused an error
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
deprecated: false
/geocode-address:
parameters: []
servers:
- url: https://neutrinoapi.net
description: Multicloud endpoint utilizing both GCP and AWS with IP anycast load balancing, DNS based geoproximity and cloud failover
variables: {}
- url: https://aws.neutrinoapi.net
description: AWS only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://gcp.neutrinoapi.net
description: GCP only endpoint utilizing IP anycast load balancing and failover
variables: {}
- url: https://neutrinoapi.com
description: Backup endpoint utilizing a seperate top-level domain and IP addresses
variables: {}
- url: https://eu.neutrinoapi.net
description: European Union geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://aus.neutrinoapi.net
description: Australia geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
- url: https://usa.neutrinoapi.net
description: United States geofence endpoint, requests to this endpoint are guaranteed to only be processed on servers within the geofence boundary
variables: {}
get:
tags:
- Geolocation
summary: Geocode Address
description: Geocode an address, partial address or just the name of a place
operationId: GeocodeAddress
parameters:
- name: address
in: query
description: The full address, partial address or name of a place to try and locate. Comma separated address components are preferred.
style: form
explode: true
schema:
type: string
examples:
- 1 Molesworth Street, Thorndon, Wellington 6011
- name: house-number
in: query
description: The house/building number to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: street
in: query
description: The street/road name to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: city
in: query
description: The city/town name to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: county
in: query
description: The county/region name to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: state
in: query
description: The state name to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: postal-code
in: query
description: The postal code to locate (for structured address searches)
style: form
explode: true
schema:
type: string
- name: country-code
in: query
description: Prefer results from this country code (the default is no country bias)
style: form
explode: true
schema:
type: string
- name: country-codes
in: query
description: Prefer results from this list of country codes (space or comma separated values). Preference is in the order supplied, you can use the 'country-code' parameter to also set a dynamic or user supplied country code which takes precedence
style: form
explode: true
schema:
type: string
- name: language-code
in: query
description: 'The language to display results in, available languages are: <ul> <li>ar, de, en, es, fr, it, ja, nl, pt, ru, zh</li> </ul>'
style: form
explode: true
schema:
type: string
default: en
- name: auto-complete
in: query
description: Enable auto-complete for search-as-you-type and search suggestions. This option can find addresses based on partial search terms, combine with 'country-code' for country specific searches. Auto-complete works best with 'fuzzy-search' disabled for the fastest response times but can be combined if required
style: form
explode: true
schema:
type: boolean
default: false
- name: fuzzy-search
in: query
description: If no matches are found for the given address, start performing a recursive fuzzy search until a geolocation is found. This option is useful for processing user supplied input that may be incomplete or have typos and where you do not mind some potential loss in precision
style: form
explode: true
schema:
type: boolean
default: false
- name: limit
in: query
description: Limit search results to this many locations (between 1 and a maximum of 32)
style: form
explode: true
schema:
type: integer
contentEncoding: int32
default: 8
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GeocodeAddressResponse'
'400':
description: Your API request has been rejected. Check error code for details
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You have failed to authenticate
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: We messed up, sorry! Your request has caused a fatal exception
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
default:
description: We messed up, sorry! Your request has caused an error
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
deprecated: false
components:
schemas:
Timezone:
title: Timezone
required:
- id
- name
- abbr
- date
- time
- offset
type: object
properties:
id:
type: string
description: The time zone ID as per the IANA time zone database (tzdata). If empty then no valid timezone was detected
examples:
- America/New_York
name:
type: string
description: The full time zone name
examples:
- Eastern Daylight Time
abbr:
type: string
description: The time zone abbreviation
examples:
- EDT
date:
type: string
description: The current date at the time zone (ISO 8601 format 'YYYY-MM-DD')
examples:
- '2021-01-01'
time:
type: string
description: The current time at the time zone (ISO 8601 format 'hh:mm:ss.sss')
examples:
- '12:30:00.00'
offset:
type: string
description: The UTC offset for the time zone (ISO 8601 format '±hh:mm')
description: Structure of timezone
GeocodeReverseResponse:
title: GeocodeReverseResponse
required:
- country
- found
- address
- city
- country-code
- postal-code
- state
- address-structured
- address-components
- country-code3
- currency-code
- location-type
- location-tags
- latitude
- longitude
- timezone
- region-code
- postal-address
- language-code
- geohash
- continent-code
- building-type
- location-profile
type: object
properties:
country:
type: string
description: The country of the location
found:
type: boolean
description: True if these coordinates map to a real location
address:
type: string
description: The full address string using comma-separated values, use 'postal-address' for the address string formatted using country/region specific rules
city:
type: string
description: The city of the location
country-code:
type: string
description: The ISO 2-letter country code of the location
postal-code:
type: string
description: The postal code for the location
state:
type: string
description: The state of the location
address-structured:
$ref: '#/components/schemas/AddressStructured'
address-components:
type: object
additionalProperties:
type: string
description: The components which make up the address such as road, city, state, etc. These are country/region specific values, use 'address-structured' for a strict address structure which is the same for all locations globally
country-code3:
type: string
description: The ISO 3-letter country code of the location
currency-code:
type: string
description: ISO 4217 currency code associated with the country
location-type:
type: string
description: 'The detected location type ordered roughly from most to least precise, possible values are: <br> <ul> <li>address - indicates a precise street address</li> <li>street - accurate to the street level but may not point to the exact location of the house/building number</li> <li>city - accurate to the city level, this includes villages, towns, suburbs, etc</li> <li>postal-code - indicates a postal code area (no house or street information present)</li> <li>railway - location is part of a rail network such as a station or railway track</li> <li>natural - indicates a natural feature, for example a mountain peak or a waterway</li> <li>island - location is an island or archipelago</li> <li>administrative - indicates an administrative boundary such as a country, state or province</li> </ul>'
location-tags:
type: array
items:
type: string
description: 'Array of strings containing any location tags associated with the address. Tags are additional pieces of metadata about a specific location, there are thousands of different tags. Some examples of tags: shop, office, cafe, bank, pub'
latitude:
type: number
description: The location latitude
longitude:
type: number
description: The location longitude
timezone:
$ref: '#/components/schemas/Timezone'
region-code:
type: string
description: The ISO 3166-2 region code for the location
postal-address:
type: string
description: The formatted address using local standards suitable for printing on an envelope
language-code:
type: string
description: The ISO 2-letter language code for the official language spoken in the country
geohash:
type: string
description: The location <a href="https://en.wikipedia.org/wiki/Geohash">geohash</a>
continent-code:
type: string
description: ISO 2-letter continent code
building-type:
type: string
description: 'The detected building type for the address, possible values are: <br> <ul> <li>none - no building type was detected for this location</li> <li>house - a residential house/property</li> <li>apartment - a residential apartment complex</li> <li>office - a commercial/business office</li> <li>accommodation - a hotel/motel or other type of accommodation</li> <li>education - a school or university</li> <li>food - a restaurant or place where food can be purchased</li> <li>shop - a shop selling any type of goods</li> <li>attraction - an attraction such as theme parks or tourist activities</li> <li>medical - a hospital or other medical facility</li> <li>transport - a transportation building such as a bus or train depot</li> <li>commercial - a commercial/industrial building</li> <li>government - a government or military facility</li> <li>public - a public building such as a townhall or community centre</li> </ul>'
location-profile:
type: object
additionalProperties:
type: string
description: 'Map containing any external metadata linked to the location. Currently supports the following values which are only set if known: website-url, phone-number, org-name, wikipedia-title, wikidata-entity'
description: Structure of geocode-reverse
examples:
- address: 1 Molesworth Street, Pipitea, Wellington 6145, New Zealand
address-components:
city: Wellington
country: New Zealand
county: Wellington City
house-number: '1'
neighbourhood: Lambton
postal-code: '6145'
road: Molesworth Street
state: Wellington
suburb: Pipitea
address-structured:
area: Pipitea
city: Wellington
country: New Zealand
county: Wellington City
name: ''
number: '1'
postal-code: '6145'
state: Wellington
street: Molesworth Street
building-type: house
city: Wellington
continent-code: OC
country: New Zealand
country-code: NZ
country-code3: NZL
currency-code: NZD
found: true
geohash: rbsm1jthekqy
language-code: en
latitude: -41.277585
location-profile: {}
location-tags:
- house
location-type: address
longitude: 174.777523
postal-address: '1 Molesworth Street
Pipitea
Wellington 6145
New Zealand'
postal-code: '6145'
region-code: WGN
state: Wellington
timezone:
abbr: NZDT
date: '2025-11-18'
id: Pacific/Auckland
name: New Zealand Daylight Time
offset: '+13:00'
time: '17:05:01.96639137'
IPInfoResponse:
title: IPInfoResponse
required:
- valid
- country
- hostname
- city
- country-code
- latitude
- region
- longitude
- continent-code
- ip
- country-code3
- currency-code
- host-domain
- timezone
- is-v6
- is-v4-mapped
- is-bogon
- region-code
- language-code
type: object
properties:
valid:
type: boolean
description: True if this is a valid IPv4 or IPv6 address
country:
type: string
description: Full country name
hostname:
type: string
description: The IPs full hostname (only set if reverse-lookup has been used)
city:
type: string
description: Name of the city (if detectable)
country-code:
type: string
description: ISO 2-letter country code
latitude:
type: number
description: Location latitude
region:
type: string
description: Name of the region (if detectable)
longitude:
type: number
description: Location longitude
continent-code:
type: string
description: ISO 2-letter continent code
ip:
type: string
description: The IPv4 or IPv6 address returned
country-code3:
type: string
description: ISO 3-letter country code
currency-code:
type: string
description: ISO 4217 currency code associated with the country
host-domain:
type: string
description: The IPs host domain (only set if reverse-lookup has been used)
timezone:
$ref: '#/components/schemas/Timezone'
is-v6:
type: boolean
description: True if this is a IPv6 address. False if IPv4
is-v4-mapped:
type: boolean
description: True if this is a <a href="https://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses">IPv4 mapped IPv6 address</a>
is-bogon:
type: boolean
description: True if this is a bogon IP address such as a private network, local network or reserved address
region-code:
type: string
description: ISO 3166-2 region code (if detectable)
language-code:
type: string
description: The ISO 2-letter language code for the official language spoken in the country
description: Structure of ip-info
examples:
- city: Hong Kong
continent-code: AS
country: China, Hong Kong Special Administrative Region
country-code: HK
country-code3: HKG
currency-code: HKD
host-domain: ''
hostname: ''
ip: 1.1.1.1
is-bogon: false
is-v4-mapped: false
is-v6: false
language-code: zh
latitude: 22.28552
longitude: 114.15769
region: Hong Kong
region-code: HK
timezone:
abbr: HKT
date: '2025-11-18'
id: Asia/Hong_Kong
name: Hong Kong Standard Time
offset: +08:00
time: '12:05:01.242079452'
valid: true
Location:
title: Location
required:
- country
- address
- city
- country-code
- country-code3
- latitude
- postal-code
- longitude
- state
- address-structured
- address-components
- currency-code
- location-type
- location-tags
- timezone
- region-code
- postal-address
- language-code
- geohash
- continent-code
- building-type
- location-profile
type: object
properties:
country:
type: string
description: The country of the location
address:
type: string
description: The full address string using comma-separated values, use 'postal-address' for the address string formatted using country/region specific rules
city:
type: string
description: The city of the location
country-code:
type: string
description: The ISO 2-letter country code of the location
country-code3:
type: string
description: The ISO 3-letter country code of the location
latitude:
type: number
description: The location latitude
postal-code:
type: string
description: The postal code for the location
longitude:
type: number
description: The location longitude
state:
type: string
description: The state of the location
address-structured:
$ref: '#/components/schemas/AddressStructured'
address-components:
type: object
additionalProperties:
type: string
description: The components which make up the address such as road, city, state, etc. These are country/region specific values, use 'address-structured' for a strict address structure which is the same for all locations globally
currency-code:
type: string
description: ISO 4217 currency code associated with the country
location-type:
type: string
description: 'The detected location type ordered roughly from most to least precise, possible values are: <br> <ul> <li>address - indicates a precise street address</li> <li>street - accurate to the street level but may not point to the exact location of the house/building number</li> <li>city - accurate to the city level, this includes villages, towns, suburbs, etc</li> <li>postal-code - indicates a postal code area (no house or street information present)</li> <li>railway - location is part of a rail network such as a station or railway track</li> <li>natural - indicates a natural feature, for example a mountain peak or a waterway</li> <li>island - location is an island or archipelago</li> <li>administrative - indicates an administrative boundary such as a country, state or province</li> </ul>'
location-tags:
type: array
items:
type: string
description: 'Array of strings containing any location tags associated with the address. Tags are additional pieces of metadata about a specific location, there are thousands of different tags. Some examples of tags: shop, office, cafe, bank, pub'
timezone:
$ref: '#/components/schemas/Timezone'
region-code:
type: string
description: The ISO 3166-2 region code for the location
postal-address:
type: string
description: The formatted address using local standards suitable for printing on an envelope
language-code:
type: string
description: The ISO 2-letter language code for the official language spoken in the country
geohash:
type: string
description: The location <a href="https://en.wikipedia.org/wiki/Geohash">geohash</a>
continent-code:
type: string
description: ISO 2-letter continent code
building-type:
type: string
description: 'The detected building type for the address, possible values are: <br> <ul> <li>none - no building type was detected for this location</li> <li>house - a residential house/property</li> <li>apartment - a residential apartment complex</li> <li>office - a commercial/business office</li> <li>accommodation - a hotel/motel or other type of accommodation</li> <li>education - a school or university</li> <li>food - a restaurant or place where food can be purchased</li> <li>shop - a shop selling any type of goods</li> <li>attraction - an attraction such as theme parks or tourist activities</li> <li>medical - a hospital or other medical facility</li> <li>transport - a transportation building such as a bus or train depot</li> <li>commercial - a commercial/industrial building</li> <li>government - a government or military facility</li> <li>public - a public building such as a townhall or community centre</li> </ul>'
location-profile:
type: object
additionalProperties:
type: string
description: 'Map containing any external metadata linked to the location. Currently supports the following values which are only set if known: website-url, phone-number, org-name, wikipedia-title, wikidata-entity'
description: Structure of locations
APIError:
title: APIError
required:
- api-error
- api-error-msg
type: object
properties:
api-error:
type: integer
description: API error code. If set and > 0 then an API error has occurred your request could not be completed
contentEncoding: int32
api-error-msg:
type: string
description: API error message
description: For non-200 responses this contains specific API error details
examples:
- api-error: 43
api-error-msg: ACCESS DENIED. USER ID OR API KEY INVALID
GeocodeAddressResponse:
title: GeocodeAddressResponse
required:
- found
- locations
type: object
properties:
found:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/neutrino-api/refs/heads/main/openapi/neutrino-api-geolocation-api-openapi.yml