Locations Service
Access info
| Endpoint | https://locations-api.socrate.io/graphql |
| Required access keys | Tenant-level service access key |
| Pricing | Please contact us for details at contact@bitsoftware.ro |
| Notes | To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to locations-api:query:* locations-api:mutation:*. |
Usage
The Locations Service enables callers to obtain a correctly formatted and structured address from unstructured and potentially incorrect or unreliable input data.
How it works
When a user enters an address into a software system, there is a chance that it may contain invalid characters, typos, wrong text formatting or even an invalid city or region. This service accepts such potentially incomplete or unreliable address information and returns a correctly formatted address. The response includes a confidence (reliability) score, or an error if there is not enough confidence in the input data.
Queries
checkLocation
Returns a correctly formatted address, derived from input data which may be incorrect or incomplete. All input parameters are optional. The more accurate are the details included in the input data, the higher the returned reliability score.
Arguments
| Argument | Type | Description |
|---|---|---|
| input | LocationInput! |
Mandatory. Provides the input data to the query. |
LocationInput input
| Attribute | Type | Description |
|---|---|---|
| country | String |
The input country of the address. This could be a two-letter country code or a country name. |
| city | String |
The input city. |
| region | String |
The input region. |
| text | String |
The input address data provided as free, unstructured text. This parameter may be provided standalone, or along with all other parameters. |
| address | String |
The input street address and number. |
Result
Location type
| Attribute | Type | Description |
|---|---|---|
| country | String |
The country of the address. |
| countryCode | String |
The 2-letter country code of the address. |
| city | String |
The city of the address. |
| cityCode | String |
The SIRUTA (in Romanian: Sistemul Informatic al Registrului Unităților Teritorial - Administrative) city code of the address. |
| region | String |
The region of the address. |
| regionCode | String |
The SIRUTA region code of the address. |
| district | String |
The district of the address. |
| address | String |
The street address component of the address. |
| postal | String |
The postal code of the address. |
| confidence | String |
The confidence score of the returned address, expressed as a percentage. |
| error | String |
The error reason, if available. |
Example
The following query returns a correctly formatted address based on some manually entered address value.
query CheckLocation($input: LocationInput!) {
checkLocation(input: $input) {
country
countryCode
city
cityCode
region
regionCode
district
address
postalCode
confidence
error
}
}
{
"input": {
"address": "str. Jepilor, 48, Brasov, Romania"
}
}
version
Returns the API version.